在 Android 网络开发中，Retrofit 结合 Gson 转换器是最常用的组合之一。当我们用 GET 请求拉取接口数据并映射成 Java 或 Kotlin 模型类时，如果服务端返回的 JSON 里包含了客户端模型并未声明的字段，Gson 默认并不会直接崩溃，而是安静地忽略它们。但现实情况往往更复杂：有些团队开启了严格模式、有些字段类型不匹配、或者你使用了混淆后字段名对不上的旧包，这时候多余字段就会变成解析异常的导火索。因此掌握如何主动忽略这些多余字段，是写稳接口层的关键一步。
使用 transient 关键字快速跳过字段
最直观的做法是在模型类中，把那些服务端可能返回但本地完全不需要的字段用 transient 修饰。Gson 在默认配置下，序列化与反序列化都会跳过被 transient 标记的成员变量。这种方式零配置，不需要改动 Retrofit 的构建代码，适合快速验证或者临时屏蔽某个引起问题的字段。
比如下面的用户模型，服务端可能多返回了 internalCode 字段，我们在客户端模型中并不关心它，就可以直接忽略：
public class User {
public String name;
public int age;
public transient String internalCode; // 服务端可能返回，但本地忽略
}
不过 transient 的局限也很明显：它是 Java 语言层面的关键字，意味着这个字段在整个 Gson 处理生命周期里都被跳过，包括你后续如果想把对象再转回 JSON 上传也会丢失。另外如果多余字段是嵌套对象里多出来的，你得去改每一个嵌套类，维护成本会上升。因此它更适合字段少、结构简单的场景。
通过 GsonBuilder 与 Expose 注解精确控制
如果你希望对“忽略哪些字段”有更细的掌控，可以使用 Gson 的 excludeFieldsWithoutExposeAnnotation 方法。开启后，Gson 只处理带了 @Expose 注解的字段，其余一律视为多余并忽略。这相当于白名单机制，比 transient 更灵活，也不会污染Java关键字语义。
在 Retrofit 中构建适配器时，把定制好的 Gson 实例塞进 GsonConverterFactory 即可：
Gson gson = new GsonBuilder()
.excludeFieldsWithoutExposeAnnotation()
.create();
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://ipipp.com/api/")
.addConverterFactory(GsonConverterFactory.create(gson))
.build();
对应的模型类需要显式标注要保留的字段：
public class User {
@Expose
public String name;
@Expose
public int age;
// 没有 @Expose，将被 Gson 忽略
public String internalCode;
public String token;
}
这种方案的优点是模型职责清晰，一眼能看出哪些字段参与解析。缺点是每个需要解析的字段都得加注解，模型类写起来稍显繁琐。如果后端突然给所有响应包了一层 meta 对象，你只需在 meta 类里不放 @Expose 就能整体忽略，扩展性不错。
自定义 TypeAdapter 与 skipValue 兜底未知字段
当接口返回结构极度不稳定，或者你不想为每一个模型类都加注解时，可以注册一个通用的 TypeAdapter 或 JsonDeserializer，在读取 JSON 时遇到未声明字段直接调用 JsonReader.skipValue() 丢弃。这样哪怕后端随便加字段，客户端也不会挂。
下面是一个简单的通用反序列化器示例，它把未知字段全部跳过，只取已知属性：
public class SafeUserAdapter implements JsonDeserializer<User> {
@Override
public User deserialize(JsonElement json, Type typeOfT, JsonDeserializationContext context) {
JsonObject obj = json.getAsJsonObject();
User user = new User();
if (obj.has("name")) user.name = obj.get("name").getAsString();
if (obj.has("age")) user.age = obj.get("age").getAsInt();
// 其他字段不读取即为忽略
return user;
}
}
在 Retrofit 的 Gson 配置中注册它：
Gson gson = new GsonBuilder()
.registerTypeAdapter(User.class, new SafeUserAdapter())
.create();
这种写法把容错逻辑集中在适配器里，模型类保持干净。对于历史包袱重、字段天天变的后端，用 skipValue 或在手动解析里不读多余键，是最省心的做法。需要注意的代价是失去了一些 Gson 自动映射的便利性，复杂嵌套时要自己写递归解析，工作量视项目规模而定。
Kotlin 数据类与 ignoreUnknown 的注意事项
使用 Kotlin 的开发者常写数据类配合 Retrofit。Kotlin 没有 transient 关键字写法，但可以用 @Transient 注解达到类似效果。另外 Moshi 作为另一个流行转换器，提供了 ignoreUnknownKeys = true 的开关，而 Gson 默认就是忽略未知键的，所以多数时候 Kotlin 项目不配置也不会因多余字段崩溃。
示例 Kotlin 模型：
data class User(
val name: String,
val age: Int,
@Transient val internalCode: String = ""
)
如果你在测试中遇到多余字段导致解析失败，优先确认是否用了自定义 Gson 或开启了严格策略，而不是怀疑 Retrofit 本身。理清转换层配置，忽略多余字段就是一行配置或几个注解的事，不必在调用层写大量判空和 try-catch。
RetrofitGsonignore_extra_fields修改时间：2026-08-16 20:12:29