SpringBoot 4 最大升级雷区！老项目瞬间炸了

深入了解 Jackson 3.0 在 Spring Boot 4.x 中的重大变更，包括包名变更、API 变化和迁移指南

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.x	Jackson 3.x	说明
JsonGenerator.Feature	JsonWriteFeature	特性枚举重命名
JsonParser.Feature	JsonReadFeature	特性枚举重命名
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. 异常处理从受检异常变为运行时异常

参考资料

• Jackson 3.0 Release Notes
• Spring Framework 7.0 Jackson 3.x Support