90%的复杂嵌套JSON解析无需自定义反序列化器；仅当字段语义与结构严重脱节（如字符串内含JSON、动态类型映射、运行时格式不一致）时才需编写JsonDeserializer，且须继承StdDeserializer、处理null、复用ObjectMapper。
直接上结论：90% 的“复杂嵌套 JSON 解析难题”，其实根本不需要写自定义反序列化器；盲目上 JsonDeserializer 反而会让代码更难维护、更易出错。真正该用自定义反序列化器的场景，是当字段语义与结构严重脱节时——比如某个字符串字段实际是嵌套 JSON、某个数字字段需按业务规则动态转成枚举、或某段结构在不同 API 版本中形态不一致。
什么时候必须写自定义 JsonDeserializer
不是“嵌套深”就要自定义，而是以下情况才值得动手：
- JSON 中某字段值是字符串，但内容其实是合法 JSON（例如
"metadata": "{"version":2,"flags":["A"]}"），需要二次解析为对象 - 字段类型在运行时动态决定（如
"type": "user"对应User类，"type": "org"对应Org类），且@JsonTypeInfo无法覆盖（比如 type 不在顶层，或 key 名不固定） - 字段原始值是字符串/数字，但需结合上下文做转换（如
"status_code": 200要转成Status.OK，而这个映射逻辑不能靠@JsonCreator简单覆盖） - 同一字段在不同环境返回格式不一致（如测试环境返回完整对象，生产环境只返回 ID 字符串），且你无法统一上游输出
怎么写一个安全可用的自定义 JsonDeserializer
关键不是“能跑”，而是“不崩、可测、易替换”。注意三点：
- 永远继承
StdDeserializer<t></t>，不要直接实现JsonDeserializer接口——否则会丢失 Jackson 内部对 null、空值、类型检查等默认处理 - 构造函数里必须调用
super(T.class)，否则反序列化时可能抛IllegalArgumentException: Can not construct instance - 在
deserialize()方法开头加if (jsonParser.getCurrentToken() == JsonToken.VALUE_NULL) return null;，否则遇到 null 字段会 NPE - 别在 deserializer 里 new
ObjectMapper——复用外部传入的或全局单例，避免线程安全和性能问题
示例：解析一个伪装成字符串的嵌套对象字段
public class MetadataDeserializer extends StdDeserializer<Metadata> {
private final ObjectMapper mapper = new ObjectMapper(); // 实际应注入或复用
public MetadataDeserializer() {
super(Metadata.class);
}
@Override
public Metadata deserialize(JsonParser jsonParser, DeserializationContext ctxt)
throws IOException {
if (jsonParser.getCurrentToken() == JsonToken.VALUE_NULL) {
return null;
}
String jsonStr = jsonParser.getText();
try {
return mapper.readValue(jsonStr, Metadata.class);
} catch (JsonProcessingException e) {
throw new JsonMappingException(jsonParser, "Failed to parse metadata JSON", e);
}
}
}
为什么 @JsonUnwrapped 和 @JsonAlias 多数时候比自定义更管用
很多所谓“复杂嵌套”，本质是结构映射没对齐。与其写一整套 deserializer，不如先检查这些轻量级方案：
-
@JsonUnwrapped(prefix = "user_")：把{"user_name":"a","user_id":1}直接塞进User字段，不用手动 flatten -
@JsonAlias({"status_code", "http_status"})：兼容历史字段名变更，一行解决 -
@JsonDeserialize(using = StatusDeserializer.class)只加在具体字段上，而不是整个类——避免污染其他字段的默认行为 - 配合
@JsonIgnoreProperties(ignoreUnknown = true)，能吃掉 70% 的“字段多出来”报错，比写逻辑更省事
容易被忽略的线程安全与缓存陷阱
自定义 deserializer 实例本身是线程安全的（无状态），但如果你在里面用了非线程安全的对象（比如自己 new 的 SimpleDateFormat），就会出问题。更隐蔽的是缓存：
- Jackson 默认会缓存 deserializer 实例，所以你在构造器里传参初始化的逻辑，只执行一次——别指望每次反序列化都重新读配置
- 如果 deser 依赖外部服务（如查字典表），务必做成懒加载 + 缓存（如 Caffeine），否则每反序列化一次就调一次远程接口
- 测试时用
new ObjectMapper().registerModule(...)是 OK 的，但生产环境要确保 module 是单例注册，否则缓存失效、GC 压力大
真正复杂的嵌套解析，难点从来不在“怎么写 deserializer”，而在“怎么让 deserializer 不成为系统瓶颈或故障点”。先确认是否真绕不开，再动手。
