Spring Boot 4 的 Jackson 3 迁移实录:包名改完,才刚开始
从 Boot 3.5 升到 4.1.1,Jackson 这条线真正花时间的不是改包名。
先改依赖和包名
三个动作:spring-boot-starter-json 换成 spring-boot-starter-jackson;定制器换成 JsonMapperBuilderCustomizer,包在 org.springframework.boot.jackson.autoconfigure;序列化相关 import 从 com.fasterxml.jackson.databind 改成 tools.jackson.databind。
这里有个坑:注解包没变。@JsonIgnore、@JsonProperty、@JsonFormat 仍在 com.fasterxml.jackson.annotation。全局替换时一起换掉,编译会挂一片。
改完这三处,编译能过、能启动、接口也返回 JSON。剩下的问题都在运行期。
映射器不再自己造
以前习惯 new ObjectMapper() 然后到处 configure。Jackson 3 是 builder 出来一个不可变实例:
java
private static final JsonMapper JSON_MAPPER = SpringUtils.getBean(JsonMapper.class);JsonUtils 直接取容器里那个。Web 线程、boundedElastic、定时任务共用一个实例,谁也没法在运行时改配置。读写方法名没变,业务代码不用动。
序列化器签名变了
Long 超过 JS 安全整数要转成字符串,这是原来的自定义序列化器。Jackson 3 里父类从 ser.std 搬到 ser.jdk,第三个参数从 SerializerProvider 变成 SerializationContext:
java
public void serialize(Number value, JsonGenerator gen, SerializationContext provider) {
if (value.longValue() >= MIN_SAFE_INTEGER && value.longValue() <= MAX_SAFE_INTEGER) {
super.serialize(value, gen, provider);
} else {
gen.writeString(value.toString());
}
}编译期能抓到的都不算麻烦。麻烦的是重写了 serializeWithType、或者直接调 provider.defaultSerializeValue 的地方,得逐个对签名。
顺带能删一个依赖:Java 时间类型已内置在 databind(ext.javatime),jackson-datatype-jsr310 不需要了。
日期格式有两处
spring.mvc.format.date-time 只管 @RequestParam、@PathVariable 的绑定。JSON 里的 LocalDateTime 走映射器上注册的序列化器。只配一处,就会看到"入参能进、返回体格式不对"。这和 Jackson 3 无关,但升级时容易一起排查。
Redis 最容易漏
Redisson 4.x 才有 TypedJsonJackson3Codec,老的 TypedJsonJacksonCodec 是 Jackson 2 的。选错不会报错,读缓存时才抛类型转换异常。
java
JsonMapper jsonMapper = JsonMapper.builder()
.addModules(simpleModule)
.activateDefaultTyping(
BasicPolymorphicTypeValidator.builder().allowIfSubType((ctxt, clazz) -> true).build(),
DefaultTyping.NON_FINAL)
.build();
TypedJsonJackson3Codec jsonCodec = new TypedJsonJackson3Codec(Object.class, jsonMapper);activateDefaultTyping 现在必须给校验器。Jackson 3 不再对外开放 LaissezFaireSubTypeValidator,上面这个写法等价于 2.x 的宽松模式;生产上建议按包名白名单。
另一个问题是老缓存。默认类型信息会把全类名写进去,这次所有类都搬了家,旧 key 反序列化就是 ClassNotFoundException。不用逐个查,把 key 前缀换一版,等于缓存整体失效。
SDK 边界上还留着一套 Jackson 2
全局搜 com.fasterxml.jackson.databind,还能找到十几处。飞书 SDK、AgentScope 的决策模型模块都还在 Jackson 2,构造百炼请求时用的就是自己的 ObjectMapper:
java
static final ObjectMapper MAPPER = new ObjectMapper()
.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE)
.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);两套并存没问题,只要别混:SDK 的 DTO 不交给全局 JsonMapper,边界处用字符串传;两套 JsonNode 类型不同,混用在编译期就会报错。
所以搜索里还剩 com.fasterxml 不代表没改完,看它出现在哪一层:在 SDK 适配层是对的,在业务代码里才是漏改。
我们的顺序
换 starter → 全局替换包名、保留注解包 → 改序列化器签名 → 改自动配置类 → 换 Redis codec 并调多态校验 → 划 SDK 边界 → 跑单测、起栈验证缓存和接口。
spring.jackson.* 的键没变,indent_output、fail_on_unknown_properties 照用。单测里 JsonMapper 直接 builder 构造,不需要 Spring 上下文。
关于 BizBuddy
BizBuddy 是全量开源(MIT)的企业级智能体平台:Spring Boot 4.1.1 + AgentScope Java Harness,前端 开源中后台底座,PostgreSQL 14 与 MySQL 8.0 双栈交付。文中的 JsonUtils、JacksonConfig、RedisConfig 都在仓库里。
仓库地址:https://gitee.com/zl3624/biz-buddy
bash
cd code/back-end && ./mvnw clean package -DskipTests
cd ../front-end && pnpm install && pnpm build:prod
cd ../../deploy/deploy-pg && docker compose up -d --build登录 http://localhost 补齐模型 Key 即可;改完代码跑 node e2e/http/run.mjs 回归。