spring-boot-4-migration

Spring Boot 4 迁移技能

将 Spring Boot 2.7.x 应用迁移到 3.5.x，再从 3.5.x 迁移到 4.x， 并根据每个迁移阶段对应的 Spring Boot 官方迁移指南和发行说明， 及时跟进 4.x 的次要版本。

时效性

最后验证时间：2026-07（Spring Boot 4.1.0 / Framework 7.0.8 时期）。本文中的信息可能会过时。如果答案取决于对版本敏感的信息——例如移除目标版本、受管依赖版本、OpenRewrite 配方 ID，或“在 X 版本中弃用”的说法——且距离上述时间戳已有一段时间，请先抽查最新发行说明或相关工具的源代码，再作出判断。如果当前文档与本文不一致，以文档为准：请说明这一点，并指出本文中的相应内容已过时。

范围：2.7.x → 3.5.x → 4.x 及 4.x 次要版本

本技能涵盖三种场景：

1. 旧版迁移（2.7.x → 3.5.x）——前置步骤。详见 references/spring-boot-2-to-3-migration.md：Java 8/11 → 17 基线、 Jakarta EE 命名空间迁移（javax.* → jakarta.*）、Spring Security 5 → 6、Hibernate 5 → 6、向 Micrometer Tracing/Observation 迁移可观测性，以及每个步骤的 OpenRewrite 配方自动化。 先升级到最新的 Boot 3.5 补丁版本，再进入下一种场景。
2. 主版本迁移（3.5.x → 4.0）——本技能的主要内容。包括全部 9 个阶段、 渐进式升级策略，以及下文的桥接系统。
3. 次要版本升级（4.0 → 4.1、4.1 → 4.2 等）——记录于 references/minor-version-changes.md。次要版本可能弃用 API、 移除兼容性桥接、更改默认值并引入新功能。升级到任何新的 4.x 次要版本前，请检查该文件。

如果你的项目使用 Boot 2.7.x 或更早版本，请先从下方的 “从 Spring Boot 2.7 迁移？”开始，完成 2 → 3 阶段，然后 返回此处继续 3 → 4 阶段。

根据当前文档验证 API

这些迁移过程中，许多 API 都会发生变化。如果不确定某个 API、 属性或模式在目标版本中是否仍然有效，请查阅资料，而不要依赖模型已有的知识：

• 使用 Context7（先调用 mcp__claude_ai_Context7__resolve-library-id， 再调用 mcp__claude_ai_Context7__query-docs）查阅库文档。
• 使用 WebSearch / WebFetch 查找重大变更公告、CVE 和社区迁移报告。
• 使用 gh 查阅发行说明（例如： gh api repos/spring-projects/spring-boot/releases/latest）。

工具链版本检查（首先执行）

开始任何迁移之前，请检测项目的 Java、Kotlin、Maven 和 Gradle 版本。如果其中任何版本低于目标 Boot 版本的最低要求，请在升级 Boot 之前先升级相应工具。

最低和推荐版本表以及各工具的升级命令，请参阅 references/toolchain-versions.md。

从 Spring Boot 2.7 迁移？从这里开始。

如果你的项目使用 Spring Boot 2.7.x（或更早版本），请先完成 2.7 → 3.5 阶段：Boot 2.7.x → Boot 3.5.x latest → Boot 4.x。

请阅读 references/spring-boot-2-to-3-migration.md。其中涵盖 工具链升级、2.7.18 迁移前检查、OpenRewrite 配方 （一次性执行 UpgradeSpringBoot_3_5 或按次要版本逐步迁移）、Jakarta 命名空间、 Security 5 → 6、Hibernate 5 → 6、属性迁移，以及向 Micrometer Tracing 迁移可观测性。

当 ./mvnw verify / ./gradlew build 在最新的 Boot 3.5 补丁版本上通过， 且 spring-boot-properties-migrator 不再输出提示后，请返回此处。

前置条件

3.x → 4.0 迁移：

• 工具链版本符合最低要求（见上文“工具链版本检查”）
• 源项目在 Spring Boot 3.5.x（最新补丁版本）上能够编译且测试通过
• 可使用 Java 17+（推荐 Java 21+，支持 Java 25）
• 尽可能解决所有 Boot 3.x 中已弃用的 API 调用
• 如果使用 Boot 3.4 或更早版本，请先升级到 3.5.x，再继续迁移

4.x → 4.y 次要版本升级：

• 项目使用当前次要版本的最新补丁版本（例如，最新的 4.0.x）
• 查看 references/minor-version-changes.md，了解目标版本的变更
• 查看目标版本的官方发布说明
• 解决当前版本中的所有弃用警告

选择迁移策略

策略 1 — 渐进式升级（推荐用于企业级/大型代码库） 首先阅读 references/gradual-upgrade-strategy.md。该策略将迁移建模为依赖关系图：第 1 天通过兼容桥接实现基线，然后可按自己的节奏完成 6 条独立轨道（Starters、Jackson 3、Properties、Security、Testing、Framework 7）。关键桥接包括：

• spring-boot-starter-classic — 恢复 3.x 单体自动配置
• spring-boot-jackson2 — 让 Jackson 2 代码在 Boot 4 下继续运行
• spring-security-access — 桥接旧版 AccessDecisionManager/Voter 适用场景：有多个团队、许多服务、分阶段发布，或完成 Jackson 3 / Security 7 迁移需要超过一个冲刺。

策略 2 — 一次性升级（如下） 在一次工作中按顺序执行全部 9 个阶段。最适合全新项目、小型代码库或由单个团队负责的项目。

使用 OpenRewrite 自动迁移

手动迁移前，可考虑使用 OpenRewrite 配方自动处理机械性变更。先运行 OpenRewrite 处理批量查找替换操作，然后使用本技能中的各阶段处理剩余的手动变更（Security DSL 重写、行为差异、属性语义等）。

对于 2.7 → 3.5 这一步（在任何 3 → 4 工作之前运行）：参见 references/spring-boot-2-to-3-migration.md 第 3 节中的配方表 — UpgradeSpringBoot_3_5 一次性配方会组合每个步骤；大型代码库也可以按次要版本逐步运行。

对于 3.5 → 4.0 这一步：

配方 ID	覆盖范围
org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0（提供 Community Edition 变体）	Boot 3.5 → 4.0
org.openrewrite.java.spring.kafka.UpgradeSpringKafka_4_0	Spring Kafka 3.x → 4.0（与 Boot 4 配方一同使用 — 参见 references/spring-kafka-4-migration.md）
org.openrewrite.java.jackson.UpgradeJackson_2_3	Jackson 2 → 3 包/导入迁移
org.openrewrite.java.spring.boot4.ReplaceMockBeanAndSpyBean	@MockBean/@SpyBean → @MockitoBean/@MockitoSpyBean

参见：moderne.ai/blog/spring-boot-4x-migration-guide。有关 4.0 配方的具体信息：docs.openrewrite.org/recipes/java/spring/boot4/upgradespringboot_4_0-community-edition。

调用方式：./mvnw org.openrewrite.maven:rewrite-maven-plugin:run -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE -Drewrite.activeRecipes=<recipe-id>（Maven）或 ./gradlew rewriteRun -Drewrite.activeRecipes=<recipe-id>（Gradle）。

迁移工作流（一次性升级）

按顺序执行以下阶段。每个阶段都必须通过编译和测试，才能进入下一阶段。

阶段 1：构建文件迁移

更新 Boot/Framework 版本和构建插件，并将已弃用的 starter 替换为模块化的对应项。为测试中使用的每种技术添加模块化测试 starter。如有需要，可暂时使用 classic starter。

阅读 references/build-and-dependencies.md，了解完整的 starter 对照表、构建插件变更和分步说明。

如果项目使用 Spring for Apache Kafka，还应阅读 references/spring-kafka-4-migration.md — Spring Kafka 4 会更改测试 starter 坐标（spring-kafka-test → spring-boot-starter-kafka-test），并提供专用的 OpenRewrite 配方，这些配方应与 UpgradeSpringBoot_4_0 一同运行。

编译检查：运行 mvn compile 或 gradle compileJava — 继续之前先修复所有依赖解析错误。

阶段 2：属性迁移

扫描所有 application.properties、application.yml、特定 profile 的变体，以及 @SpringBootTest(properties = ...) 注解。重命名已变更的属性键（Jackson、MongoDB、会话、Actuator、Hibernate）。

阅读 references/property-changes.md，了解完整的属性映射。

阶段 3：Jackson 3 迁移

Jackson 3 是 Boot 4 的默认版本。迁移 group ID、包以及已重命名的 Boot 类（@JsonComponent → @JacksonComponent 等）。 如有需要，可暂时使用 spring-boot-jackson2 桥接模块。

阅读 references/jackson3-migration.md，了解完整详情。 如果项目使用 Spring Kafka JSON 序列化器/反序列化器或标头映射器，也请阅读 references/spring-kafka-4-migration.md 中的 Jackson 部分——Kafka 序列化器代码将移至 tools.jackson.* 包树。

阶段 4：包和 API 迁移

修复已迁移的导入（@EntityScan、BootstrapRegistry 等）、已移除的 API（PropertyMapper.alwaysApplyingNotNull、路径匹配选项）以及已弃用的转换器。适用时，还要迁移 HTTP 客户端代码。

阅读 references/api-changes.md，了解已迁移包和已移除 API 的完整列表。 如果项目使用 RestClient、WebClient、@HttpExchange 或 Feign，也请阅读 references/http-clients.md。

阶段 5：可观测性迁移

将独立的 Micrometer/OTel 依赖替换为整合后的 spring-boot-starter-opentelemetry starter，更新 OTLP 属性，并重命名可观测性模块。现在导出 OTel 时 Actuator 已是可选项。

阅读 references/observability-migration.md，了解完整详情。

阶段 6：Spring Security 7 迁移

迁移至 Security 7 DSL（仅支持 lambda，不再使用 and()），替换已移除的 AuthorizationManager#check，切换到 PathPatternRequestMatcher，并更新 Jackson/SAML 集成。如果旧版 AccessDecisionManager/Voter 代码暂时无法迁移，请使用 spring-security-access 桥接模块。

阅读 references/spring-security7.md，了解完整详情。

阶段 7：测试基础设施迁移

将 @MockBean/@SpyBean 替换为 @MockitoBean/@MockitoSpyBean（已移除，而非仅弃用）。为测试 HTTP 客户端添加显式的自动配置注解。迁移 Testcontainers 2 模块名称/包，并采用 JUnit 6。为每种技术添加模块化测试 starter。

阅读 references/testing-migration.md，了解完整详情。 如果项目使用 @EmbeddedKafka 或 EmbeddedKafkaZKBroker，也请阅读 references/spring-kafka-4-migration.md——Spring Kafka 4 移除了 ZooKeeper 代码路径（仅支持 KRaft）以及相应的 @EmbeddedKafka 属性。

阶段 8：Spring Framework 7 特定变更

处理 JSpecify 空值性（对 Kotlin 的影响）、已弃用的 AntPathMatcher、MVC XML 配置移除、SpringExtension 范围变更、Hibernate 7.1 实体映射变更，以及 Spring Retry → Framework 核心重试的迁移。

阅读 references/spring-framework7.md，了解完整详情。 如果项目使用 Spring Retry、@Retryable、@ConcurrencyLimit 或 Resilience4j，也请阅读 references/resilience-migration.md。 如果项目使用 Spring for Apache Kafka，也请阅读 references/spring-kafka-4-migration.md——Spring Kafka 4 不再依赖 Spring Retry，改用 Framework 7 核心重试；BackOffValuesGenerator 现在使用 BackOff 而非 BackOffPolicy。 也可选读 references/api-versioning.md，了解 Framework 7 引入的新 API 版本控制功能。

阶段 9：最终验证

如果有验证脚本，请运行；否则请手动检查：

1. mvn clean verify 或 gradle clean build — 完整编译和测试
2. 验证应用能否启动：mvn spring-boot:run 或 gradle bootRun
3. 检查 actuator 健康状态：curl localhost:8080/actuator/health
4. 验证存活和就绪探针（现已默认启用）
5. 检查结构化日志的输出格式
6. 针对每个启用的 Spring 配置文件运行集成测试
7. 如果使用 buildpacks 或 Jib，请验证 Docker 镜像能否构建

如果计划采用 AOT 处理、GraalVM 原生镜像或新的 AOT 缓存功能，可选读 references/aot-native.md。

次要版本升级（4.0 → 4.1、4.1 → 4.2 等）

在 Spring Boot 4.x 次要版本之间升级时，请遵循以下流程：

1. 检查变更内容

阅读目标版本对应的 references/minor-version-changes.md。另请参阅官方发行说明：

• https://github.com/spring-projects/spring-boot/wiki（各版本的发行说明）
• https://docs.spring.io/spring-boot/upgrading.html

2. 注意兼容性桥接的移除

兼容性桥接会在次要版本中移除。升级前，请检查你依赖的桥接是否即将弃用：

桥接	引入版本	预计移除版本
spring-boot-jackson2	4.0	4.3.0（根据 Javadoc forRemoval）
spring-boot-starter-classic	4.0	5.0
spring-boot-starter-test-classic	4.0	5.0
已弃用的 starter 名称	4.0	5.0

如果你仍在使用目标版本中即将移除的桥接，请在升级前完成相应的迁移路径。

3. 升级流程

1. 将构建文件中的 Spring Boot 版本更新为目标次要版本的最新补丁版本。
2. 运行 mvn compile / gradle compileJava — 修复所有新的编译错误。
3. 运行完整测试套件 — 修复所有测试失败。
4. 检查构建输出和应用日志中的弃用警告。这些警告表明下一个次要版本中会有哪些内容失效。
5. 运行 verify_migration.sh 确认迁移状态。

4. 新功能

每个次要版本都会引入新功能和自动配置。这些功能均为可选，不要求采取任何操作，但你可能会想要采用。请查看各版本发行说明中的“新增内容”部分。

故障排查

常见编译错误

错误	原因	修复方法
ClassNotFoundException: ...autoconfigure...	需要模块化 starter	添加特定的 spring-boot-starter-X
NoSuchMethodError: PropertyMapper.alwaysApplyingNotNull	API 已移除	改用 always()
Cannot resolve symbol JsonComponent	已重命名	使用 @JacksonComponent
Package com.fasterxml.jackson does not exist	Jackson 3 包	改为 tools.jackson
Cannot resolve symbol MockBean	已弃用或移除	使用 @MockitoBean
ClassNotFoundException: RestClientBuilderCustomizer	Elasticsearch 变更	使用 Rest5ClientBuilderCustomizer

快速修复

• 如果升级版本后构建完全无法编译，可使用 spring-boot-starter-classic 和 spring-boot-starter-test-classic 先让项目运行起来，然后逐步迁移到模块化 starter。完整的 Day-1 基线请参阅 references/gradual-upgrade-strategy.md。
• 如果 Jackson 3 迁移造成阻碍，可临时添加 spring-boot-jackson2。这是官方支持的桥接 — 请参阅渐进式迁移策略中的 Track B。
• 如果 Spring Security 的变更较多，可添加 spring-security-access 桥接，并先完成升级到 Security 6.5 的准备步骤（这些步骤提供了用于选择退出 7.0 重大变更的标志）。请参阅渐进式迁移策略中的 Track D。
• 对于涉及许多服务的企业级推广，请采用 references/gradual-upgrade-strategy.md 中的 Wave 1-4 方法，以尽量缩小影响范围。

参考文件索引

文件	阅读时机
references/toolchain-versions.md	工具链检查 — Java/Kotlin/Maven/Gradle 最低版本及各工具的升级命令
references/spring-boot-2-to-3-migration.md	Boot 2.7.x → 3.5.x 前置步骤 — Java 基线、Jakarta 迁移、Hibernate 5 → 6、Security 5 → 6、OpenRewrite 配方、各次小版本更新亮点
references/gradual-upgrade-strategy.md	首先阅读（适用于 3 → 4）— 迁移依赖图、桥接方案、独立轨道、企业级推出
references/build-and-dependencies.md	阶段 1 / 轨道 A — 完整的 starter 映射表、构建插件变更
references/property-changes.md	阶段 2 / 轨道 C — 所有属性键重命名和取值变更
references/jackson3-migration.md	阶段 3 / 轨道 B — Jackson 3 包、API、兼容模式
references/api-changes.md	阶段 4 — 包迁移、移除的 API、重命名的类
references/observability-migration.md	阶段 5 — OpenTelemetry starter、OTLP 属性、模块重命名、Actuator 解耦
references/spring-security7.md	阶段 6 / 轨道 D — Security 7 破坏性变更和 DSL 迁移
references/testing-migration.md	阶段 7 / 轨道 E — 2.7→3 测试环节（JUnit 4→5、javax→jakarta 测试），然后是 3.5→4：MockBean、Testcontainers 2、JUnit 6、RestTestClient
references/spring-framework7.md	阶段 8 / 轨道 F — Framework 7 变更、JSpecify、路径匹配
references/http-clients.md	HTTP 客户端 — RestClient、WebClient、@HttpExchange、Feign 迁移、RestTestClient
references/api-versioning.md	API 版本控制 — 策略、语义范围、客户端、弃用、测试
references/resilience-migration.md	弹性 — Spring Retry → Framework 7、@Retryable、@ConcurrencyLimit、Resilience4j
references/spring-kafka-4-migration.md	Spring for Apache Kafka 4 — Apache Kafka 4 客户端（仅限 KRaft）、移除 EmbeddedKafkaZKBroker、spring-boot-starter-kafka-test、Jackson 3 序列化器、移除 Spring Retry、KIP-848 / KIP-932、OpenRewrite 配方
references/aot-native.md	AOT/Native — BeanRegistrar、RuntimeHints、Spring Data AOT、GraalVM 25、AOT Cache
references/minor-version-changes.md	4.x 小版本升级 — 各小版本的变更、移除桥接方案、新功能
scripts/verify_migration.sh	阶段 9 — 支持桥接方案的验证，结果为 PASS/FAIL/WARN/BRIDGE

每个环节的权威外部来源列于相应参考文件末尾。