前言

最近在做 Spring Boot 4 升级的时候，发现一个非常普遍的现象——大部分人被 Jackson 3 这个“隐形炸弹”炸得措手不及。

项目启动后控制台报了一堆莫名其妙的错。

翻来覆去一看。原来不是业务代码的问题，是 Jackson 升级带来的破坏性变更。

“Jackson 不就是个 JSON 序列化工具吗？一下能有什么大不了的，”

如果你这么想，那说明你还没真正理解 Jackson 在 Java 环境中的位置。话说回来，

Jackson 不仅仅是“一个 JSON 库”。它是 Java 环境中的 JSON 标准实现。

Spring Boot、微服务通信、Redis 序列化、日志解析——几乎所有涉及到 JSON 的地方，底层都在用 Jackson。

从 Jackson 2.x 升级到 3.x，绝不是一次“无感升级”。它是 Jackson 时隔 8 年 的第一次大版本号变更。

从 2017 年底开始酝酿，到 2025 年 10 月 3 日发布 GA 版本。前后经历了 10 个 RC 版本。不过，

今天这篇文章，我把 Jackson 3 的新功能和迁移要点从头到尾拆解一遍。

更多项目实战请访问我的技术网站：

一、Jackson 3 到底 “新” 在哪？

在聊具体功能之前，我们先建立一个整体认知。 Jackson 3 是一次价值取向非常明确的重构型演进。

• If Jackson 2 更偏向“兼容一切历史包袱”，那么 Jackson 3 的目标非常清晰——安全、类型清晰、面向现代 Java
• 下面这张概览图基本概括了 Jackson 3 的主要变化
• 接下来我会逐一给你拆解每个痛点所在的改动

二、JDK 基线升级到 Java 17+

This is most fundamental change.

• Jackson 2.x 最低支持 JDK 8；Jackson 3 将最低基线提高至 JDK 17。
• This means you can now leverage modern language features such as Records,Sealed Classes and Pattern Matching.
• Your pain point：If your project still runs on JDK 8/11,you will hit compile‑time errors as soon as you add a Jackson 3 dependency. You must upgrade JDK first.
• The good news: Spring Boot 4 already requires JDK 17。so most new projects are already ready.

三、包名和 groupId 全面变更

// Jackson 2.x
import com.fasterxml.jackson.databind.ObjectMapper;怎么说呢，import com.fasterxml.jackson.core.JsonParser;// Jackson 3.x
import tools.jackson.databind.json.JsonMapper;import tools.jackson.core.JsonParser;

Pain point：The very first compilation error after upgrading is “cannot find symbol” for all imports that still use .fasterxml.. A global search‑replace in your IDE is required.

The annotation package stays unchanged on purpose so that a project can run both Jackson 2 and Jackson 3 simultaneously.

四、ObjectMapper 变成不可变的 JsonMapper

The mutable ObjectMapper in Jackson 2 often leads to hidden bugs in multi‑threaded environments:

// mutable configuration – dangerous in concurrency
ObjectMapper mapper = new ObjectMapper;mapper.enable;mapper.disable;...
// anor thread may change same mapper at runtime → unpredictable results

The new design forces a Builder pattern and makes mapper immutable after construction:

// Immutable JsonMapper – safe to share across threads
JsonMapper jsonMapper = JsonMapper.builder
.enable
.disable
.build;// configuration locked

You also have to use format‑specific subclasses instead of mixing factories:

// Correct usage per format
JsonMapper json = JsonMapper.builder.build;// JSON
YAMLMapper yaml = YAMLMapper.builder.build;// YAML
XmlMapper xml = XmlMapper.builder.build;// XML
// ❌ Wrong: new ObjectMapper)

Pain point：If you previously instantiated mappers with custom factories )),those lines will no longer compile and must be replaced with appropriate subclass builder.

五、异常程序重构：检查型 → 非检查型

Sorry but this table seems incomplete due to formatting issues.

Let's rewrite it correctly.