外观
Spring Boot 4 Jackson 配置与迁移
约 1012 字大约 3 分钟
Spring Boot 4JacksonJSON迁移指南
次阅读
2026-04-09
Jackson 3 — 最大的破坏性变更
Spring Boot 4 将 JSON 库从 Jackson 2 升级到 Jackson 3。这是此次升级中影响面最广的破坏性变更。
为什么影响大？
Jackson 3 对 Jackson 2 不完全兼容，核心变化包括：
| 变更项 | Jackson 2（Spring Boot 3.x） | Jackson 3（Spring Boot 4.x） |
|---|---|---|
| 核心包名 | com.fasterxml.jackson | tools.jackson |
| Maven Group ID | com.fasterxml.jackson.* | tools.jackson.* |
| 注解包名 | com.fasterxml.jackson.annotation | 不变，注解模块保持原包名 |
注意：
jackson-annotations模块的com.fasterxml.jackson.coreGroupId 和com.fasterxml.jackson.annotation包名没有变。
类名重命名
Spring Boot 4 中 Jackson 相关的工具类也做了重命名：
| 旧名称（Spring Boot 3.x） | 新名称（Spring Boot 4.x） | 用途 |
|---|---|---|
JsonObjectSerializer | ObjectValueSerializer | JSON 序列化器基类 |
JsonValueDeserializer | ObjectValueDeserializer | JSON 反序列化器基类 |
Jackson2ObjectMapperBuilderCustomizer | JsonMapperBuilderCustomizer | ObjectMapper 定制接口 |
@JsonComponent | @JacksonComponent | 注册自定义序列化/反序列化组件 |
@JsonMixin | @JacksonMixin | 注册 Mixin 类 |
迁移示例
// Spring Boot 3.x
@Configuration
public class JacksonConfig {
@Bean
public Jackson2ObjectMapperBuilderCustomizer customizer() {
return builder -> builder.dateFormat(new SimpleDateFormat("yyyy-MM-dd"));
}
}
// Spring Boot 4.x
@Configuration
public class JacksonConfig {
@Bean
public JsonMapperBuilderCustomizer customizer() {
return builder -> builder.dateFormat(new SimpleDateFormat("yyyy-MM-dd"));
}
}配置属性变更
属性路径重组
# Spring Boot 3.x
spring:
jackson:
serialization:
indent-output: true
write-dates-as-timestamps: false
deserialization:
fail-on-unknown-properties: false
parser:
allow-comments: true
# Spring Boot 4.x（JSON 专有属性已重组）
spring:
jackson:
json:
read: # 对应 Jackson 3 的 JsonReadFeature
allow-comments: true
write: # 对应 Jackson 3 的 JsonWriteFeature
indent-output: true模块自动发现行为变更
Spring Boot 4 中，Jackson 会自动检测 classpath 上的所有模块并注册到 mapper 实例。而 Spring Boot 3 中只有"已知模块"会自动注册。
如果不需要此行为：
spring.jackson.find-and-add-modules=false新的 Jackson Starter
<!-- Spring Boot 4.x 专用 Jackson starter（Jackson 3） -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-jackson</artifactId>
</dependency>三种 Jackson 2 兼容方案
如果你暂时不想迁移到 Jackson 3，Spring Boot 4 提供了三种兼容方案。
方案一：使用兼容性默认值（推荐）
让 Jackson 3 的行为尽量对齐 Jackson 2：
spring.jackson.use-jackson2-defaults=true这是最简单的方案，适合 Jackson 使用不复杂的项目。
方案二：使用 Jackson 2 兼容模块
引入专门的 Jackson 2 兼容模块（已标记为 Deprecated，仅作过渡）：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-jackson2</artifactId>
</dependency>Jackson 2 的配置属性在 spring.jackson2.* 下，与 Spring Boot 3.5 的 spring.jackson.* 一致：
spring:
jackson2:
serialization:
indent-output: true
deserialization:
fail-on-unknown-properties: false方案三：按模块指定 Jackson 2
如果你只是某个特定模块需要 Jackson 2，可以精确指定：
# HTTP 消息转换器使用 Jackson 2
spring.http.converters.preferred-json-mapper=jackson2
spring.http.codecs.preferred-json-mapper=jackson2
# GraphQL RSocket 使用 Jackson 2
spring.graphql.rsocket.preferred-json-mapper=jackson2
# WebSocket Messaging 使用 Jackson 2
spring.websocket.messaging.preferred-json-mapper=jackson2
# RSocket 使用 Jackson 2
spring.rsocket.preferred-mapper=jackson2常用配置示例
基础配置
spring:
jackson:
# 日期格式
date-format: yyyy-MM-dd HH:mm:ss
# 时区
time-zone: Asia/Shanghai
# 默认属性包含策略
default-property-inclusion: non_null
json:
write:
indent-output: true
read:
allow-comments: true
allow-single-quotes: true自定义序列化/反序列化
// Spring Boot 4.x 使用 @JacksonComponent
@JacksonComponent
public class LocalDateTimeSerializer extends ObjectValueSerializer<LocalDateTime> {
public LocalDateTimeSerializer() {
super(LocalDateTime.class);
}
@Override
public void serialize(LocalDateTime value, JsonGenerator gen, SerializerProvider serializers)
throws IOException {
gen.writeString(value.format(DateTimeFormatter.ISO_LOCAL_DATE_TIME));
}
}Mixin 使用
// Spring Boot 4.x 使用 @JacksonMixin
@JacksonMixin(type = User.class)
public abstract class UserMixin {
@JsonProperty("user_name")
private String name;
@JsonIgnore
private String password;
}迁移建议
- 新项目：直接使用 Jackson 3，配合
spring-boot-starter-jackson - 简单项目：方案一（
use-jackson2-defaults=true）最快 - 重度依赖 Jackson 2 的项目：方案二（
spring-boot-jackson2）过渡，逐步迁移 - 混合场景：方案三按模块精细控制
Jackson 3 的包名变化是硬伤——所有 import com.fasterxml.jackson 都需要改为 import tools.jackson（注解包除外）。建议配合 IDE 的全局替换功能批量处理。
相关文章：