Skip to main content
Spring Boot 4.x 将随 Spring Framework 7.x 一起发布，其中最重要的变更之一就是从 Jackson 2.x 升级到 Jackson 3.x。这次升级带来了许多破坏性变更，需要开发者特别注意。 最近在群里讨论 Spring Boot 4.x 的变更，大家的反应基本都是：“这改动真是一坨大的！” 作为一个在 Spring 生态摸爬滚打多年的开发者，看到这次 Jackson 3.0 的变更真的是五味杂陈： 不过说实话，这些改进对于大部分业务场景来说，远不如迁移成本来得实在。

​
主要破坏性变更

​
1. 包名和 GroupId 变更

最重大的变更是包名的完全重构： 旧的 Jackson 2.x： 
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
新的 Jackson 3.x： 
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>

import tools.jackson.databind.ObjectMapper;
import tools.jackson.core.JsonProcessingException;
注意： jackson-annotations 仍然保持在 com.fasterxml.jackson 包下不变。

​
2. ObjectMapper 构建方式变更

Jackson 2.x 方式： 
ObjectMapper mapper = new ObjectMapper();
mapper.configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, true);
mapper.configure(JsonGenerator.Feature.ESCAPE_NON_ASCII, true);
Jackson 3.x 强制使用 Builder 模式： 
import tools.jackson.databind.json.JsonMapper;

ObjectMapper mapper = JsonMapper.builder()
    .enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
    .enable(JsonWriteFeature.ESCAPE_NON_ASCII)
    .build();
重要变更： ObjectMapper 和 JsonFactory 在 Jackson 3.x 中变为不可变对象，必须使用 Builder 模式创建。

​
3. 异常处理变更

Jackson 2.x： 
try {
    Person person = mapper.readValue(json, Person.class);
} catch (IOException e) {
    // 必须捕获 IOException
    log.error("JSON parsing failed", e);
}
Jackson 3.x： 
// JacksonException 现在继承 RuntimeException
Person person = mapper.readValue(json, Person.class);
// 不再需要强制捕获异常，但仍可以选择性捕获

​
4. API 方法签名变更

方法重命名和移除：
Jackson 2.xJackson 3.x说明
JsonGenerator.FeatureJsonWriteFeature特性枚举重命名
JsonParser.FeatureJsonReadFeature特性枚举重命名
DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES保持不变API 保持兼容

​
5. 类型处理变更

泛型和类型引用： Jackson 2.x： 
TypeReference<List<Person>> typeRef = new TypeReference<List<Person>>() {};
List<Person> persons = mapper.readValue(json, typeRef);
Jackson 3.x： 
// 基本用法保持不变，但内部实现有优化
TypeReference<List<Person>> typeRef = new TypeReference<List<Person>>() {};
List<Person> persons = mapper.readValue(json, typeRef);

​
Spring Boot 4.x 集成影响

​
1. 自动配置变更

Spring Boot 4.x 的 Jackson 自动配置将适配新的 API： 
@Configuration
public class JacksonConfig {
    
    @Bean
    @Primary
    public ObjectMapper objectMapper() {
        return JsonMapper.builder()
            .enable(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY)
            .disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES)
            .build();
    }
}

​
2. Spring MVC 集成

Controller 中的使用保持基本不变： 
@RestController
public class ApiController {
    
    @PostMapping("/api/users")
    public ResponseEntity<User> createUser(@RequestBody User user) {
        // Spring Boot 4.x 将自动使用 Jackson 3.x 进行序列化/反序列化
        return ResponseEntity.ok(userService.create(user));
    }
}

​
3. 配置属性调整

application.yml 中的 Jackson 配置需要验证兼容性： 
spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false
    deserialization:
      fail-on-unknown-properties: false
    # 某些属性名可能发生变化，需要查阅最新文档

​
迁移策略

​
1. 逐步迁移计划

阶段 1：依赖更新 
<!-- 更新所有 Jackson 相关依赖 -->
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.0.0</version>
</dependency>
阶段 2：包名替换 
# 使用 IDE 的全局搜索替换功能
com.fasterxml.jackson.databind -> tools.jackson.databind
com.fasterxml.jackson.core -> tools.jackson.core
阶段 3：代码重构
  • 将所有 ObjectMapper 创建改为 Builder 模式
  • 移除不必要的异常捕获
  • 更新特性配置代码

​
2. 自动化迁移工具

使用 OpenRewrite 进行自动迁移： 
<plugin>
    <groupId>org.openrewrite.maven</groupId>
    <artifactId>rewrite-maven-plugin</artifactId>
    <version>5.40.2</version>
    <configuration>
        <activeRecipes>
            <recipe>org.openrewrite.java.jackson.UpgradeJackson_2_3</recipe>
        </activeRecipes>
    </configuration>
</plugin>
运行迁移： 
mvn rewrite:run

​
总结

Jackson 3.0 在 Spring Boot 4.x 中的升级是一次重大变更，主要影响包括：
  1. 包名从 com.fasterxml.jackson 变更为 tools.jackson
  2. 强制使用 Builder 模式创建 ObjectMapper
  3. 异常处理从受检异常变为运行时异常

​
参考资料