SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场spring-boot-4-migration

spring-boot-4-migration

部署与运维

查看项目

更新于 10-15 12:33

技能介绍

用途

本技能用于引导 Spring Boot 项目的版本迁移，覆盖三类场景：

  1. 旧版迁移（2.7.x → 3.5.x）——迁移前置阶段；
  2. 主版本迁移（3.5.x → 4.0）——本技能的主体内容；
  3. 小版本升级（4.0 → 4.1、4.1 → 4.2 等）。

迁移内容锚定官方 Spring Boot 迁移指南与各版本发布说明。技能标注最后验证时间为 2026-07（Spring Boot 4.1.0 / Framework 7.0.8 时期），并提示版本敏感事实（如移除目标、托管依赖版本、OpenRewrite 配方 ID、弃用声明）需以当前发布说明或工具源码复核；当现行文档与本文件冲突时，以文档为准。

主要能力

  • 工具链版本检查：在迁移前检测 Java、Kotlin、Maven、Gradle 版本，低于目标 Boot 版本最低要求时先行升级。
  • 2.7.x → 3.5.x 前置迁移：涵盖 Java 8/11 → 17 基线、Jakarta EE 命名空间迁移（javax.* → jakarta.*）、Spring Security 5 → 6、Hibernate 5 → 6、向 Micrometer Tracing/Observation 的可观测性迁移，以及 OpenRewrite 配方自动化。
  • 3.5.x → 4.0 主迁移：包含 9 个阶段、渐进式升级策略和桥接系统。
  • 4.x 小版本升级跟踪：小版本可能弃用 API、移除兼容桥、更改默认值并引入新特性。

使用方式

技能要求在执行迁移前先完成工具链版本检查，并提供了前置条件：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.0.x 最新），查阅目标版本的变更说明并解决当前版本的弃用警告。

提供两种迁移策略：

  • 策略一 渐进式升级（推荐用于企业级/大型代码库）：先阅读 references/gradual-upgrade-strategy.md。该策略把迁移建模为依赖图——使用兼容桥的 Day-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 完整迁移需超过一个迭代的情况。
  • 策略二 一次性迁移：按顺序执行全部 9 个阶段。适合全新项目、小型代码库或单一团队负责的情况。

技能建议先考虑用 OpenRewrite 配方自动化机械性变更，再处理剩余手工变更。3.5 → 4.0 相关配方包括：

  • org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0（另有 Community Edition 变体）
  • org.openrewrite.java.spring.kafka.UpgradeSpringKafka_4_0
  • org.openrewrite.java.jackson.UpgradeJackson_2_3
  • org.openrewrite.java.spring.boot4.ReplaceMockBeanAndSpyBean

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

一次性迁移的 9 个阶段

  1. 构建文件迁移：更新 Boot/Framework 版本、构建插件，用模块化 starter 替换弃用 starter，为测试使用的技术添加模块化测试 starter；必要时用 classic starter 作为过渡。使用 Spring for Apache Kafka 时还需处理 Spring Kafka 4 的测试 starter 坐标变更（spring-kafka-test → spring-boot-starter-kafka-test）。
  2. 属性迁移：扫描 application.properties、application.yml、profile 变体及 @SpringBootTest(properties = ...)，重命名变更的属性键（Jackson、MongoDB、session、actuator、Hibernate）。
  3. Jackson 3 迁移：Boot 4 默认使用 Jackson 3，迁移 group ID、包名和重命名的 Boot 类（@JsonComponent → @JacksonComponent 等），可用 spring-boot-jackson2 桥接过渡。
  4. 包与 API 重定位：修复重定位的导入（@EntityScan、BootstrapRegistry 等）、移除的 API（PropertyMapper.alwaysApplyingNotNull、路径匹配选项）和弃用转换器，并迁移 HTTP 客户端代码。
  5. 可观测性迁移：用整合后的 spring-boot-starter-opentelemetry 替换单个 Micrometer/OTel 依赖，更新 OTLP 属性并重命名可观测性模块；Actuator 对 OTel 导出变为可选。
  6. Spring Security 7 迁移：迁移到 Security 7 DSL（仅 lambda，无 and()），替换移除的 AuthorizationManager#check，改用 PathPatternRequestMatcher，更新 Jackson/SAML 集成；旧式 AccessDecisionManager/Voter 代码可用 spring-security-access 桥接。
  7. 测试基础设施迁移：用 @MockitoBean/@MockitoSpyBean 替换已被移除的 @MockBean/@SpyBean，为测试 HTTP 客户端添加显式自动配置注解，迁移 Testcontainers 2 的模块名/包名并采用 JUnit 6；使用 @EmbeddedKafka 或 EmbeddedKafkaZKBroker 时还需处理 Spring Kafka 4 移除 ZooKeeper 路径（仅 KRaft）及相应属性。
  8. Spring Framework 7 特定变更：处理 JSpecify 空值性（影响 Kotlin）、弃用的 AntPathMatcher、MVC XML 配置移除、SpringExtension 作用域变更、Hibernate 7.1 实体映射变更，以及 Spring Retry 向 Framework 核心重试的迁移；使用 Spring Kafka 时处理其去除 Spring Retry 依赖、BackOffValuesGenerator 改用 BackOff 等变更。
  9. 最终验证：运行完整编译与测试、验证应用启动、检查 actuator 健康端点、验证默认启用的存活/就绪探针、检查结构化日志输出、对每个活跃 Spring profile 运行集成测试、验证 Docker 镜像构建（如使用 buildpacks 或 Jib）。

小版本升级流程

查阅目标版本变更说明与官方发布说明（https://github.com/spring-projects/spring-boot/wiki、https://docs.spring.io/spring-boot/upgrading.html）；注意小版本是兼容桥被移除的节点——spring-boot-jackson2 计划在 4.3.0 移除（依据 Javadoc forRemoval），spring-boot-starter-classic 与 spring-boot-starter-test-classic 计划在 5.0 移除，弃用 starter 名称计划在 5.0 移除；若仍在使用将被移除的桥，需先完成对应迁移轨道。随后更新构建文件中的 Boot 版本至目标小版本最新补丁、编译修复错误、运行完整测试、审查构建输出与应用日志中的弃用警告，并运行 verify_migration.sh 确认迁移状态。各小版本引入的新特性与自动配置为可选，可按需采用。

适用场景

适用于需要将既有 Spring Boot 应用在不同版本之间迁移的开发者与团队，尤其是从 2.7.x 或 3.5.x 升级到 4.x 的项目，以及多服务、多团队的企业级分阶段迁移。

限制

资料中明确：本技能内容具有时效性，版本敏感事实需复核当前发布说明或工具源码，文档冲突时以官方文档为准。技能未编造具体收费、价格、平台或效果信息。