Google Gson 常见问题排查指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00285/article/details/148361601

Google Gson 常见问题排查指南

gson A Java serialization/deserialization library to convert Java Objects into JSON and back 项目地址: https://gitcode.com/gh_mirrors/gs/gson

前言

Google Gson 是 Java 生态中广泛使用的 JSON 处理库，但在实际使用过程中开发者可能会遇到各种问题。本文将从技术原理角度深入分析常见问题的成因，并提供专业解决方案，帮助开发者更好地理解和使用 Gson。

类型转换问题

症状

反序列化后出现 ClassCastException

原因分析

代码未使用类型安全的方式处理泛型
混淆工具（如 ProGuard/R8）配置不当导致类型信息丢失

解决方案

避免使用原始类型，推荐使用 TypeToken：

// 错误方式
List list = gson.fromJson(json, List.class);

// 正确方式
Type type = new TypeToken<List<MyClass>>(){}.getType();
List<MyClass> list = gson.fromJson(json, type);

优先使用带有 TypeToken 参数的 fromJson 方法重载
避免捕获类型变量，改用 TypeToken.getParameterized()

反射访问问题

模块系统相关错误

症状：出现 InaccessibleObjectException，提示模块未开放

解决方案：

对于自有模块，在 module-info.java 中添加开放声明：
```
opens mypackage to com.google.gson;
```
对于第三方类，应编写自定义 TypeAdapter 而非依赖反射

技术原理

Java 模块系统（JPMS）自 Java 9 引入，Gson 需要通过模块声明获得反射权限。对于 JDK 17+，平台类的反射访问已被完全禁止（JEP 403）。

Android 特有问题

发布版本异常

症状：Debug 正常但 Release 版本出现随机字段名

解决方案：

配置 ProGuard/R8 保留字段名：

-keepclassmembers class com.example.** { *; }

使用 @SerializedName 注解提供备选名称：

@SerializedName(value = "username", alternate = {"a", "b"})
String userName;

版本兼容性问题

症状：应用更新后无法解析旧版数据

解决方案：

保持字段命名一致性
利用映射文件追踪混淆变化
使用 @SerializedName 维护向后兼容性

序列化/反序列化行为问题

默认值丢失

症状：字段默认值在反序列化后失效

原因：Gson 使用 Unsafe API 绕过构造函数

解决方案：

确保类为静态（static）且有无参构造

禁用不安全实例化：

new GsonBuilder().disableJdkUnsafe().create();

匿名类问题

症状：匿名/局部类被序列化为 null

解决方案：转换为静态嵌套类

技术说明：双括号初始化（double brace）会创建匿名类，应避免使用。

JSON 处理问题

格式异常

症状：MalformedJsonException

排查技巧：

检查 JSON 路径（JSONPath）定位问题
使用 IDE 的 JSON 验证功能

示例错误：

{
  "languages": [
    "English",
    "French",  // 错误的尾随逗号
  ]
}

数字类型问题

症状：整型被解析为 double

解决方案：

new GsonBuilder()
    .setObjectToNumberStrategy(ToNumberPolicy.LONG_OR_DOUBLE)
    .create();

高级配置建议

严格模式

推荐启用严格模式以确保符合 JSON 规范：

new GsonBuilder()
    .setStrictness(Strictness.STRICT)
    .create();

空值处理

序列化时包含 null：

new GsonBuilder().serializeNulls().create();

自定义适配器处理 null：

@Override
public MyClass read(JsonReader in) throws IOException {
    if (in.peek() == JsonToken.NULL) {
        in.nextNull();
        return null;
    }
    // ...正常处理
}