升到 Spring Boot 4.0：先稳住 3.5.x，再拆模块与配置

要把现有应用迁到 Spring Boot 4.0，官方迁移指南给出的顺序很明确：先升到最新的 3.5.x，再动大版本。这样可以先把依赖和弃用 API 在旧线上清干净，再面对 4.0 的模块拆分和配置改名。[1]

准备工作

• 运行时：Java 17 及以上（建议用当前 LTS）；Kotlin 需 2.2+；若用 GraalVM native-image，需 v25+。

• Spring Boot 4 基于 Jakarta EE 11，Servlet 基线为 6.1；自行管依赖时须对齐 Spring Framework 7.x。

• 对照官方 3.5.x 与 4.0.x 的依赖管理差异；Spring Cloud 等未由 Boot 托管的组件，先查清兼容版本再升。

• 列一张「本项目用到的技术清单」：WebMVC/WebFlux、JPA、Flyway、Security、Kafka、Batch 等，后面要按清单换 starter。

操作步骤

1、升到最新 3.5.x 并清掉弃用调用

先把工程升到最新可用的 3.5.x 维护版，编译跑通测试。逐个检查对已弃用类/方法的调用——这些在 4.0 会被删除。做完这一步，再改 BOM 到 4.0 最新维护版。[1]

怎么确认成功： 工程在 3.5.x 上构建、测试全绿，且业务代码触发的 deprecation 警告已清理或有替换方案。

2、用 properties migrator 兜住配置改名

4.0 里不少 application.properties / application.yml 键被重命名或删除。可临时加入：

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-properties-migrator</artifactId>
  <scope>runtime</scope>
</dependency>

Gradle 则用 runtimeOnly("org.springframework.boot:spring-boot-properties-migrator")。启动时它会打印诊断，并在运行期临时迁移旧键。迁移完成后务必删掉该依赖。[1]

怎么确认成功： 启动日志里旧键告警消失，配置已改成新键名，去掉 migrator 后行为不变。

3、按技术补齐 starter，必要时先用 classic 过渡

4.0 改成更细的模块：例如以前只引 Flyway/Liquibase 第三方包就能自动配置，现在要换成 spring-boot-starter-flyway / spring-boot-starter-liquibase。测试侧同理，优先用 spring-boot-starter-<tech>-test。若一时理不清依赖，可先用 spring-boot-starter-classic（及 spring-boot-starter-test-classic）把 classpath 拉回“全家桶”形态，修导入和跑通后再去掉 classic、按技术补 starter。[1]

旧名 starter 也有一批弃用替换，例如 spring-boot-starter-web → spring-boot-starter-webmvc，OAuth 相关 starter 名称也加了 security- 前缀，建议对照官方表一次性改完。[1]

4、过一遍破坏性变更清单

Undertow 嵌入式支持已移除（未对齐 Servlet 6.1）；Jackson 默认走向 Jackson 3（包名/坐标从 com.fasterxml.jackson 迁到 tools.jackson，注解模块例外）；@MockBean/@SpyBean 改为 @MockitoBean/@MockitoSpyBean；@SpringBootTest 不再默认带上 MockMVC，需要时加 @AutoConfigureMockMvc。Mongo 等属性前缀也有调整（部分 spring.data.mongodb.* 改为 spring.mongodb.*）。[1]

怎么确认成功： 应用能启动，核心接口与集成测试通过；若仍依赖 Jackson 2，可临时引入 spring-boot-jackson2，但应排期迁到 Jackson 3。

注意事项

• 已移除能力还包括：Pulsar Reactive 自动配置、Unix 可执行 uber jar 启动脚本、Spock 集成、Spring Session Hazelcast/MongoDB 的 Boot 侧直接支持等。

• 同步阅读 Spring Framework 7、Security 7、Data 2025.1 等同批发行说明，避免只升 Boot、下游仍卡在旧大版本。

说明：步骤据 Spring Boot 官方 Wiki《Spring Boot 4.0 Migration Guide》整理，Wiki 页面最近编辑时间为 2026 年 6 月 28 日；具体以你锁定的 4.0.x 维护版发行说明为准。

来源

[1] Spring Boot 4.0 Migration Guide，Spring Boot Wiki，页面最近编辑 2026年6月28日。

#SpringBoot #SpringBoot4 #Java #迁移指南 #JakartaEE