Java record 反序列化时如何处理额外 JSON 字段

Java record 反序列化遇到 JSON 新增字段时，是否报错不由 record 语法单独决定，而由 Jackson 的未知属性策略决定。最小改法是给需要兼容的 record 加上 @JsonIgnoreProperties(ignoreUnknown = true)；如果一组接口都采用同一策略，再为对应的 ObjectMapper 或 ObjectReader 配置 FAIL_ON_UNKNOWN_PROPERTIES。已声明组件的类型校验仍然保留。

把“额外字段”与“缺失字段、类型错误”分开处理：只想兼容服务端新增字段时，用局部忽略未知属性；需要严格发现字段漂移时保持默认失败，不要为了一个 record 全局关闭检查。

额外字段为什么会让 record 反序列化失败

record 的组件会成为数据对象的固定组成部分，例如 id 和 name。如果上游 JSON 又返回了当前版本没有建模的 tier，Jackson 会把它视为未知属性。官方文档对 FAIL_ON_UNKNOWN_PROPERTIES 的定义是：开启时遇到没有可绑定成员的字段抛出映射异常，关闭时忽略它。

因此要先判断是哪一种不兼容：

用注解给单个 record 放宽边界

当只有某个外部接口允许向前增加字段，可以把策略贴在对应 record 上。下面的写法保留 id、name 的正常绑定，同时跳过未知字段：

import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
import com.fasterxml.jackson.databind.ObjectMapper;

// 只让这个数据类型兼容上游新增字段
@JsonIgnoreProperties(ignoreUnknown = true)
public record OrderRecord(String id, String name) {
}

// mapper 仍负责把 JSON 映射到 record 的规范构造器
ObjectMapper mapper = new ObjectMapper();
OrderRecord order = mapper.readValue(
    "{\"id\":\"A-100\",\"name\":\"键盘\",\"tier\":\"pro\"}",
    OrderRecord.class
); // tier 被忽略，id 与 name 仍参与绑定

ignoreUnknown 的含义是“没有可接受成员的属性可以被忽略”，并不等于忽略所有输入问题。比如 id 必须是字符串时，传入对象仍应被当作类型错误处理。对关键业务对象，局部注解通常比修改共享 mapper 更容易评估影响。

全局 mapper 和 ObjectReader 怎么划范围

如果某个客户端面对的所有响应都采用向前兼容策略，可以配置专用 mapper：

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectMapper;

// 只给兼容型客户端使用，不要随手改共享默认 mapper
ObjectMapper compatibleMapper = new ObjectMapper()
    .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
OrderRecord order = compatibleMapper.readValue(json, OrderRecord.class);

// 严格入口继续使用默认策略，尽早暴露服务端契约漂移
ObjectMapper strictMapper = new ObjectMapper();
OrderRecord checked = strictMapper.readValue(json, OrderRecord.class);

更细的做法是复用同一个 mapper，只在一次读取时构造 ObjectReader：

import com.fasterxml.jackson.databind.DeserializationFeature;
import com.fasterxml.jackson.databind.ObjectReader;

// 兼容策略只作用于这个 reader，不改变 mapper 的其他调用者
ObjectReader reader = mapper.readerFor(OrderRecord.class)
    .without(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
OrderRecord order = reader.readValue(json); // 只放宽当前读取入口

上线前用四组输入检查兼容性

不要只拿一份“正常 JSON”确认能读。至少准备四组固定样例：带 tier 的新增字段、缺少 name 的旧数据、把 id 改成对象的错误类型，以及把上游字段名改成别名后的数据。逐组确认预期是成功、默认值、异常还是显式迁移。

实践中建议把未知字段策略写在客户端名称或读取方法旁边，例如 compatibleMapper 只服务可演进的外部响应，内部配置和管理数据继续保持严格。这样以后排查“字段没生效”时，先看实际使用的是哪个 mapper/reader，而不是只看 record 声明。

常见问题

record 能像普通 JavaBean 一样添加无参构造器吗？

不能按普通 Bean 的思路处理。record 的组件和规范构造器是类型结构的一部分，反序列化应确认 Jackson 版本及其 record 支持，再检查组件名、类型和注解位置。

关闭 FAIL_ON_UNKNOWN_PROPERTIES 会忽略缺失字段吗？

不会。它针对的是输入里多出来、无法绑定的字段；缺失组件和类型不匹配仍需按各自规则处理。

注解和全局配置同时存在时先看什么？

先看实际反序列化入口使用的 mapper 或 reader，再看 record 上的注解。把策略放宽到更大范围前，先用一组含未知字段的样例确认影响对象。

相关依据

record 的类型语义可参考 Java SE Record API；未知属性的默认行为和按调用配置方式可参考 Jackson Deserialization Features；局部忽略未知字段的注解定义见 JsonIgnoreProperties API。