Spring Boot 4.0 迁移核心注意点总结

Spring Boot 4.0 是重大版本升级，核心变化围绕基础环境升级、功能移除 / 调整、模块化重构、依赖与 API 变更四大维度，以下是需重点关注的迁移注意点，按优先级和影响范围分类，便于项目迁移落地。

一、基础环境与前置准备（必做步骤）

1. 版本前置要求

迁移前必须先升级到 Spring Boot 3.5.x 最新维护版本，彻底清理项目中所有已标记为 @Deprecated 的 API、方法及配置（Spring Boot 4.0 已完全移除 3.x 系列的废弃内容）。
JDK 强制要求：必须使用 JDK 17 及以上版本（推荐采用最新 LTS 版本，如 JDK 21），低于 JDK 17 的项目需优先完成 JDK 升级。
底层依赖基线：Spring Framework 7.x、Jakarta EE 11、Servlet 6.1（所有依赖需适配此基线）。

2. 依赖兼容性检查

非 Spring Boot 管控的第三方依赖（如 Spring Cloud、自定义组件），需提前查阅官方文档确认 4.0 兼容版本，避免版本冲突；
移除或替换 Spring Boot 4.0 不再管理的依赖：
- Spring Retry：依赖管理已移除，需手动指定版本（建议迁移到 Spring Framework 原生重试特性）；
- Spring Authorization Server：已归入 Spring Security 管理，不再提供独立版本属性，需通过 spring-security.version 控制版本。

二、核心功能移除（直接影响项目运行，需重点处理）

移除的功能	对项目的影响	替代方案
Undertow 嵌入式服务器支持	项目若使用 Undertow 作为嵌入式服务器，升级后将无法启动（Undertow 暂不兼容 Servlet 6.1）	切换为 Tomcat、Jetty 或 Reactor Netty；禁止部署到非 Servlet 6.1 兼容的外部容器
Pulsar Reactive 自动配置	依赖 Spring Pulsar Reactive 客户端的项目，自动配置失效	放弃 Reactive 客户端，改用普通 Pulsar 客户端；或自行适配 Spring Pulsar 最新版本（已移除 Reactor 支持）
嵌入式 Uber Jar 启动脚本	仅支持 Unix-like 系统的 "完全可执行 Jar" 脚本失效，无法通过脚本直接启动应用	推荐使用 Gradle Application 插件构建可执行程序；仍可通过 `java -jar xxx.jar` 方式运行 Uber Jar
Spring Session Hazelcast/MongoDB	项目若使用这两种存储的 Spring Session，自动配置和依赖管理失效	改用对应厂商维护的独立版本（Hazelcast/MongoDB 团队接管后续维护），手动引入依赖并配置
Spock 测试框架集成	基于 Spock 的测试用例无法运行（Spock 暂不支持 Groovy 5）	等待 Spock 版本升级；或临时替换为 JUnit 5 + Mockito 测试组合
经典 Uber-Jar Loader 实现	构建配置中指定 `CLASSIC` 加载器的项目，打包后无法启动	删除构建文件中的 `loaderImplementation = CLASSIC` 配置（Maven/Gradle 均需移除），使用默认加载器

三、模块化与 Starter 重大调整（依赖配置必改）

1. 模块化重构核心变化

Spring Boot 4.0 采用 "小模块" 设计，拆分原有大 Jar 包为专注于单一功能的模块；
若项目使用 Spring Boot 官方 Starter POM，大部分依赖无需手动调整（Starter 已适配模块化）；
非 Starter 方式引入依赖的项目（直接依赖核心模块），需补全模块化拆分后的缺失依赖（尤其是测试模块）。

2. Starter 依赖关键调整

（1）新增 "主 Starter + 测试 Starter" 配对模式

所有技术栈均提供独立的 "主依赖 Starter" 和 "测试 Starter"，需检查测试依赖是否完整：

示例：AspectJ 对应 spring-boot-starter-aspectj（主）+ spring-boot-starter-aspectj-test（测试）；
影响：项目原有测试依赖若未使用对应测试 Starter，可能导致测试类无法加载、自动配置失效。

（2）废弃 / 重命名的 Starter（必须替换）

废弃的 Starter	替代 Starter	备注
spring-boot-starter-oauth2-authorization-server	spring-boot-starter-security-oauth2-authorization-server	归入 Spring Security 体系
spring-boot-starter-oauth2-client	spring-boot-starter-security-oauth2-client	同上
spring-boot-starter-oauth2-resource-server	spring-boot-starter-security-oauth2-resource-server	同上
spring-boot-starter-web	spring-boot-starter-webmvc	核心变更！原 `spring-boot-starter-web` 已拆分，MVC 场景用此替代
spring-boot-starter-web-services	spring-boot-starter-webservices	命名标准化，功能不变

（3）AOP Starter 重命名说明

原 spring-boot-starter-aop 重命名为 spring-boot-starter-aspectj；
迁移建议：
- 若项目仅使用 Spring AOP 核心功能（无需 AspectJ 编译器 / 织入器），可评估是否移除该 Starter（Spring 核心模块已包含基础 AOP 支持）；
- 若依赖 AspectJ 特性（如 @AspectJ 注解、编译时织入），需替换为新 Starter。

（4）经典 Starter（临时兼容方案）

提供 spring-boot-starter-classic 和 spring-boot-starter-test-classic，兼容 Spring Boot 3.x 的依赖结构（包含所有自动配置类）；
注意：官方不推荐长期使用，仅作为迁移过渡方案，后续版本将移除。

3. 包结构调整影响

核心模块包名统一为 org.springframework.boot.<module>（如 spring-boot-webmvc 模块对应 org.springframework.boot.webmvc）；
关键类包路径变更（需修改导入语句）：
- BootstrapRegistry：从 org.springframework.boot → org.springframework.boot.bootstrap；
- EnvironmentPostProcessor：从 org.springframework.boot.env → org.springframework.boot；
自定义 Starter 注意：不建议同一 artifact 同时兼容 Spring Boot 3.x 和 4.0，需单独构建适配 4.0 的版本。

四、核心 API 与配置变更（代码 / 配置必改）

1. 核心 API 变更

（1）Nullability 注解替换

新增 JSpecify 空值注解（org.jspecify.annotations.Nullable/NonNull），替换原有 org.springframework.lang.Nullable；
影响范围：
- Actuator 端点参数：不再支持 org.springframework.lang.Nullable，需改用 JSpecify 注解声明可选参数；
- 项目自定义代码：若使用 null 检查工具（如 Kotlin 空安全、FindBugs），需批量替换注解。

（2）PropertyMapper API 行为变更

默认行为：源值为 null 时，不再调用目标方法（原版本会调用并传入 null）；
移除方法：alwaysApplyingNotNull() 已删除；
迁移示例：

java 复制代码

// 原代码（源值为 null 时仍调用 destination.method(null)）
map.from(source::method).to(destination::method);
// 4.0 等效代码（需显式声明支持 null 值）
map.from(source::method).always().to(destination::method);

（3）其他 API 废弃与替换

废弃 API / 类	替代方案
HttpMessageConverters	改用 `ClientHttpMessageConvertersCustomizer`（客户端）或 `ServerHttpMessageConvertersCustomizer`（服务端）
@JsonComponent / @JsonMixin	重命名为 `@JacksonComponent` / `@JacksonMixin`（明确绑定 Jackson，而非通用 JSON）
Jackson2ObjectMapperBuilderCustomizer	重命名为 `JsonMapperBuilderCustomizer`（适配 Jackson 3）

2. 配置属性变更（需更新 application.yml/properties）

（1）Spring Session 配置属性重命名

原属性前缀	新属性前缀	示例
spring.session.redis.	spring.session.data.redis.	原 `spring.session.redis.timeout` → `spring.session.data.redis.timeout`
spring.session.mongodb.	spring.session.data.mongodb.	原 `spring.session.mongodb.collection-name` → `spring.session.data.mongodb.collection-name`

（2）MongoDB 配置属性拆分与重命名

基础连接属性（无需 Spring Data MongoDB）：从 spring.data.mongodb.* → spring.mongodb.*：
- 示例：spring.data.mongodb.host → spring.mongodb.host；
- 涉及属性：host、port、database、username、password、uri 等；
需 Spring Data MongoDB 的属性（如 auto-index-creation、field-naming-strategy）保留 spring.data.mongodb.* 前缀；
管理类属性：mongo 替换为 mongodb：
- 原 management.health.mongo.enabled → management.health.mongodb.enabled；
新增必填配置：
- spring.mongodb.representation.uuid：显式配置 UUID 序列化规则（无默认值）；
- spring.data.mongodb.representation.big-decimal：显式配置 BigDecimal/BigInteger 序列化规则（无默认值）。

（3）其他关键配置变更

原配置	新配置 / 说明
spring.devtools.livereload.enabled	默认值从 `true` 改为 `false`，需热重载需手动设为 `true`
spring.dao.exceptiontranslation.enabled	重命名为 `spring.persistence.exceptiontranslation.enabled`
spring.jackson.read.* / spring.jackson.write.*	移至 `spring.jackson.json.read.` / `spring.jackson.json.write.`（适配 Jackson 3）
management.endpoint.health.probes.enabled	默认值从 `false` 改为 `true`，自动暴露 liveness/readiness 探针，无需可设为 `false`

3. Jackson 3 升级（核心兼容点）

（1）核心变更

默认依赖 Jackson 3，groupId 从 com.fasterxml.jackson 改为 tools.jackson（仅 jackson-annotations 仍保留 com.fasterxml.jackson.core groupId）；
包路径变更：部分核心类包路径调整（如 com.fasterxml.jackson.databind → tools.jackson.databind）。

（2）兼容方案

方案 1：全面迁移到 Jackson 3（推荐）：
- 替换项目中 Jackson 相关导入语句；
- 重命名自定义 @JsonComponent 为 @JacksonComponent；
方案 2：临时兼容 Jackson 2（不推荐长期使用）：
- 引入 spring-boot-jackson2 模块（已标记废弃）；
- 配置属性从 spring.jackson.* 改为 spring.jackson2.*；
- 启用 Jackson 2 兼容默认值：spring.jackson.use-jackson2-defaults=true；
特殊场景：Jersey 4.0 暂不支持 Jackson 3，需引入 spring-boot-jackson2 处理 JSON 序列化。

五、测试框架调整（测试代码必改）

1. Mockito 相关变更

移除 MockitoTestExecutionListener，项目中 @Mock、@Captor 等注解无法自动生效；
迁移方案：在测试类上添加 @ExtendWith(MockitoExtension.class)（Mockito 原生扩展）。

2. 集成测试注解调整

@SpringBootTest 不再自动提供以下功能，需手动添加对应注解：

所需功能	需添加的注解	备注
MockMVC	`@AutoConfigureMockMvc`	HtmlUnit 配置移至 `@HtmlUnit` 注解（如 `@AutoConfigureMockMvc(htmlUnit = @HtmlUnit(webClient = false))`）
WebTestClient	`@AutoConfigureWebTestClient`	-
TestRestTemplate	`@AutoConfigureTestRestTemplate`	推荐替换为 `RestTestClient` + `@AutoConfigureRestTestClient`
RestTestClient	`@AutoConfigureRestTestClient`	Spring Boot 4.0 新增，替代 TestRestTemplate

3. TestRestTemplate 兼容处理

若项目继续使用 TestRestTemplate，需添加测试依赖：
<dependency> <groupId>org.springframework.boot\</groupId> <artifactId>spring-boot-resttestclient\</artifactId> <scope>test</scope> </dependency>
包路径更新：从 org.springframework.boot.test.web.client.TestRestTemplate → org.springframework.boot.resttestclient.TestRestTemplate。

六、其他关键调整

1. 构建配置变更

Maven 可选依赖：默认不再打包到 Uber Jar 中，需显式配置 <includeOptional>true</includeOptional> 才能包含；
CycloneDX Gradle 插件：最低支持版本提升到 3.0.0，需升级插件版本。

2. Web 功能调整

静态资源路径：新增 /fonts/** 到默认静态资源路径，继承原有安全配置；无需则通过以下代码排除：

java 复制代码

pathRequest.toStaticResources().atCommonLocations().excluding(StaticResourceLocation.FONTS);

3. 数据功能调整

Elasticsearch：
- 低级别 RestClient 替换为 Rest5Client，自定义客户端需改用 Rest5ClientBuilderCustomizer；
- 移除 elasticsearch-rest-client、elasticsearch-rest-client-sniffer 依赖管理（已整合到 elasticsearch-java 模块）；
@EntityScan：注解从原包路径移至 org.springframework.boot.persistence.autoconfigure.EntityScan，需更新导入语句；
Hibernate：
- hibernate-jpamodelgen 替换为 hibernate-processor；
- 移除 hibernate-proxool、hibernate-vibur 依赖管理（不再发布）。

4. 消息功能调整

Kafka Streams：移除 StreamBuilderFactoryBeanCustomizer，改用 Spring Kafka 的 StreamsBuilderFactoryBeanConfigurer（实现 Ordered 接口，默认优先级 0）；
Kafka 重试：spring.kafka.retry.topic.backoff.random 重命名为 spring.kafka.retry.topic.backoff.jitter；
Spring AMQP 重试：移除 RabbitRetryTemplateCustomizer，改用 RetrySettingsCustomizer 和 RabbitListenerRetrySettingsCustomizer。

七、迁移优先级建议（按实施顺序）

环境准备：升级 JDK 到 17+，升级项目到 Spring Boot 3.5.x 并清理废弃 API；
依赖替换 ：替换重命名 / 废弃的 Starter（尤其是 spring-boot-starter-web → spring-boot-starter-webmvc）；
核心适配：移除 Undertow 依赖，切换兼容的 Web 服务器；处理 Jackson 3 升级（或启用临时兼容方案）；
测试修复 ：补全测试注解（如 @AutoConfigureMockMvc），替换 Mockito 扩展，修复 TestRestTemplate 依赖和包路径；
配置更新：批量修改变更的配置属性（Spring Session、MongoDB、Jackson 等）；
API 细节：调整 PropertyMapper 用法、空值注解、包路径导入等细节；
优化过渡：移除经典 Starter、Jackson 2 兼容模块等临时方案，适配 4.0 原生特性。

总结

Spring Boot 4.0 迁移的核心是 "适配基础环境升级、替换废弃依赖 / API、兼容模块化拆分"，优先处理影响项目启动的关键问题（如 JDK 升级、Starter 替换、Web 服务器切换），再逐步优化细节。建议按模块分批迁移，每批迁移后通过单元测试和集成测试验证功能完整性，降低迁移风险。