Debug 正常、Release 失败：Gson 与 R8 泛型响应解析排查

在维护使用 Retrofit + Gson 的 Android 项目时，常会遇到一类 Debug 与 Release 表现不一致的问题：抓包可以看到服务端接口返回了 HTTP 200 和结构完整的 JSON，在 Android Studio 中直接运行也正常；但打成开启代码压缩与优化（isMinifyEnabled = true）的 Release 包安装后，列表页加载却进入了失败态。

排查过程中还容易出现一种干扰现象：测试机复现失败后，连接电脑重新运行安装，页面又恢复了正常，容易被误判为本地缓存异常或偶发网络波动。实际上通过 IDE 直接运行安装的是未开启 R8 的 Debug 包，构建变体发生变化后，问题也就被暂时掩盖了。

定位这类问题时，除了核对源码声明，更直接的方式是检查编译优化后的字节码产物中保留了哪些元数据。

1. 泛型签名擦除与 `LinkedTreeMap` 转换异常

先用一个最小模型查看 Retrofit + Gson 依赖的字节码信息（以下字节码输出在 JDK 21.0.6 下使用 javac 与 javap -v 验证）。

假设接口外层有统一泛型包装 ApiResponse<T>，业务分页数据为 PageDto：

data class ApiResponse<T>(
  @SerializedName("code") val code: Int,
  @SerializedName("data") val data: T?,
)

data class PageDto(
  @SerializedName("items") val items: List<String>,
  @SerializedName("total") val total: Int,
)

interface FeedApi {
  @GET("feed/list")
  suspend fun fetchPage(@Query("page") page: Int): ApiResponse<PageDto>
}

熟悉 JVM 类型擦除的话就会注意到：编译成字节码之后，方法的普通描述符（descriptor）里原本就已经没有 <PageDto> 了。Retrofit 和 Gson 在运行时之所以还能知道 T 具体是 PageDto，完全依赖编译器额外写进 .class / .dex 文件里的 Signature 元数据属性。

在未经过 R8 裁剪（或规则完整保留）时，用 javap -v 查看接口方法的字节码属性如下：

  public abstract demo.ApiResponse<demo.PageDto> fetchPage(int);
    descriptor: (I)Ldemo/ApiResponse;
    Signature: #8 // (I)Ldemo/ApiResponse<Ldemo/PageDto;>;

而在开启 R8（特别是 AGP 8.0+ 默认启用的 R8 full mode）之后，如果 PageDto 在整个工程的字节码里没有任何显式的 new PageDto(...) 调用点——因为它完全是由 Gson 在运行时通过反射构造的——R8 的静态可达性分析就可能判定 PageDto 从未被实例化，进而裁剪该类或将其在泛型签名中的引用退化改写为 java.lang.Object：

  public abstract demo.ApiResponse<java.lang.Object> fetchPage(int);
    descriptor: (I)Ldemo/ApiResponse;
    Signature: #8 // (I)Ldemo/ApiResponse<Ljava/lang/Object;>;

一旦编译产物里的 Signature 变成了 ApiResponse<Object>，运行时的执行过程如下：

网络请求正常返回 200，JSON 字符串交给 Gson；
Gson 读取到的目标字段类型不再是具体的 PageDto，而是 java.lang.Object；
面对一段 JSON 对象 { "items": [...], "total": 12 } 且目标类型为 Object 时，Gson 的内置 ObjectTypeAdapter 会将其反序列化为通用的键值映射表（通常为 com.google.gson.internal.LinkedTreeMap），并写入 ApiResponse.data——此时反序列化步骤本身不会抛出异常；
等到上层业务代码读取 response.data?.items 时，字节码执行强制类型转换 (PageDto) response.data，随即抛出 java.lang.ClassCastException: com.google.gson.internal.LinkedTreeMap cannot be cast to ...，被外层协程的 runCatching 或统一错误处理捕获后，界面就表现为“接口返回了数据，页面却显示加载失败”。

2. 从异常现场到 APK 产物的排查步骤

遇到“Debug 正常、Release 解析失败”时，可以按下面四步逐一核对：

先保留安装包与异常现场：不要一开始就清除应用数据或直接用 IDE 覆盖安装。先把出现问题的包体版本、构建变体（Debug / Release）和捕获到的原始异常类型（如 EOFException、JsonSyntaxException、HTTP 502 或 ClassCastException）记录清楚。如果外层仓库把所有异常都归并成了同一个布尔失败态，先在测试日志或本地可调试的 Release 变体里输出真实异常栈。
直接检查问题 APK 的 DEX 泛型签名：把出问题的 .apk 拖进 Android Studio 的 Build → Analyze APK...（或使用命令行 apkanalyzer / dexdump），配合同次构建生成的 mapping.txt 找到对应的 Retrofit 接口与外层包装类，查看方法上的泛型 Signature 是否仍指向预期的数据类，以及目标 DTO 的字段与构造路径是否保留。
区分四项常见规则的作用范围：
- @SerializedName("...")：解决的是“字段名被混淆成 a、b 后与 JSON key 对不上”的问题；但它不会阻止一个从未在代码中显式 new 过的类被 R8 full mode 当作未实例化类型裁剪。
- -keepattributes Signature, InnerClasses, EnclosingMethod：保留泛型签名属性本身；但如果签名里引用的具体 DTO 类没有被保留，R8 依然可能改写或剥离签名里的目标类型。
- -keepclassmembers vs -keep：-keepclassmembers 只承诺“假如这个类最终存活且被实例化，则保留其成员”，在 R8 full mode 下并不足以单独阻止未显式实例化的反射 DTO 被优化掉；反射反序列化的目标模型需要明确保留类本身及其构造与字段契约（或使用 @Keep 注解标记数据模型，允许无反射需求的其他内部类正常压缩）。
修复前后用开启 R8 的产物做完整验证：

# 保留泛型与注解元数据（R8 full mode 下配合反射解析必需）
-keepattributes Signature, InnerClasses, EnclosingMethod, RuntimeVisibleAnnotations

# 对由 Gson 反射实例化的网络响应模型：使用 @SerializedName 绑定字段名，
# 并按项目实际的响应模型基类、注解（如 @androidx.annotation.Keep）或独立 dto 包精确声明保留范围：
-keep @androidx.annotation.Keep class * { <init>(...); <fields>; }

（注：具体规则应结合项目自身的 R8 版本、Gson 版本自带的 consumer rules 以及 Kotlin 默认参数构造方式核对，避免使用过于宽泛的 -keep class com.example.** { *; } 导致代码压缩与优化失效。）

3. 验证边界与技术选型延伸

在做最终回归时，还有两处边界需要留意：

本地 JVM 单元测试不能替代 Release 包验证：在 test/ 目录下直接执行 Gson().fromJson(...) 测试的是未经过 R8 压缩的原始字节码，只能验证 @SerializedName 和 JSON 结构映射是否正确，覆盖不到 R8 full mode 裁剪 Signature 的路径；最终验收需要在开启了 isMinifyEnabled = true 的构建产物上走通真实接口入口，覆盖嵌套列表、空列表与可空字段分支。
新老项目的演进取舍：既有项目已经大量使用 Gson 时，按上述链路补齐 @SerializedName 与精确的模型保留规则是改动较小、风险可控的做法；如果是从零搭建新的 Kotlin / Android 网络层，可以优先评估 kotlinx.serialization 或开启编译期代码生成的 Moshi——解析器在编译期直接生成显式的构造调用代码，不再依赖运行时反射推断哪些 DTO 需要保留。即便采用代码生成方案，升级构建链后同样需要运行开启 R8 的 Release 包进行确认。

1. 泛型签名擦除与 LinkedTreeMap 转换异常

2. 从异常现场到 APK 产物的排查步骤

3. 验证边界与技术选型延伸

1. 泛型签名擦除与 `LinkedTreeMap` 转换异常