> ## Documentation Index
> Fetch the complete documentation index at: https://blog.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 的变更真的是五味杂陈：

**不过说实话，这些改进对于大部分业务场景来说，远不如迁移成本来得实在。**

![](https://minio.pigx.vip/oss/202509/1759073983626.jpeg)

## 主要破坏性变更

### 1. 包名和 GroupId 变更

**最重大的变更是包名的完全重构：**

**旧的 Jackson 2.x：**

```xml theme={null}
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>
```

```java theme={null}
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.core.JsonProcessingException;
```

**新的 Jackson 3.x：**

```xml theme={null}
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>
```

```java theme={null}
import tools.jackson.databind.ObjectMapper;
import tools.jackson.core.JsonProcessingException;
```

> **注意：** `jackson-annotations` 仍然保持在 `com.fasterxml.jackson` 包下不变。

### 2. ObjectMapper 构建方式变更

**Jackson 2.x 方式：**

```java theme={null}
ObjectMapper mapper = new ObjectMapper();
mapper.configure(MapperFeature.SORT_PROPERTIES_ALPHABETICALLY, true);
mapper.configure(JsonGenerator.Feature.ESCAPE_NON_ASCII, true);
```

**Jackson 3.x 强制使用 Builder 模式：**

```java theme={null}
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：**

```java theme={null}
try {
    Person person = mapper.readValue(json, Person.class);
} catch (IOException e) {
    // 必须捕获 IOException
    log.error("JSON parsing failed", e);
}
```

**Jackson 3.x：**

```java theme={null}
// 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：**

```java theme={null}
TypeReference<List<Person>> typeRef = new TypeReference<List<Person>>() {};
List<Person> persons = mapper.readValue(json, typeRef);
```

**Jackson 3.x：**

```java theme={null}
// 基本用法保持不变，但内部实现有优化
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：

```java theme={null}
@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 中的使用保持基本不变：**

```java theme={null}
@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 配置需要验证兼容性：**

```yaml theme={null}
spring:
  jackson:
    serialization:
      write-dates-as-timestamps: false
    deserialization:
      fail-on-unknown-properties: false
    # 某些属性名可能发生变化，需要查阅最新文档
```

## 迁移策略

### 1. 逐步迁移计划

**阶段 1：依赖更新**

```xml theme={null}
<!-- 更新所有 Jackson 相关依赖 -->
<dependency>
    <groupId>tools.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>3.0.0</version>
</dependency>
```

**阶段 2：包名替换**

```bash theme={null}
# 使用 IDE 的全局搜索替换功能
com.fasterxml.jackson.databind -> tools.jackson.databind
com.fasterxml.jackson.core -> tools.jackson.core
```

**阶段 3：代码重构**

* 将所有 ObjectMapper 创建改为 Builder 模式
* 移除不必要的异常捕获
* 更新特性配置代码

### 2. 自动化迁移工具

**使用 OpenRewrite 进行自动迁移：**

```xml theme={null}
<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>
```

运行迁移：

```bash theme={null}
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](https://github.com/FasterXML/jackson/wiki/Jackson-Release-3.0#major-changesfeatures-in-30)
* [Spring Framework 7.0 Jackson 3.x Support](https://github.com/spring-projects/spring-framework/issues/33798)