如何自动化识别并更新Spring Boot 3升级中的依赖版本？

从一个Spring Boot 2.7项目升级到3.0/3.1时，最让人崩溃的不是Java 17的强制要求，也不是javax到jakarta的包名替换，而是项目里那一大堆第三方依赖的版本兼容性问题。比如springdoc-openapi从1.x升到2.x、Ehcache从3.8升到3.10、MyBatis Plus从3.5.2升到3.5.5，这些散落在pom.xml或build.gradle里的版本号，靠肉眼一个个核对既慢又容易出错。实际上，社区已经提供了成熟的自动化方案，能够扫描构建文件、识别过时或不兼容的依赖，并直接生成修改建议甚至执行改写。下面就从原理到实操，把这几类工具讲清楚。

为什么依赖版本自动化识别如此重要

Spring Boot 3是一次大版本跳跃，它基于Spring Framework 6，强制要求Java 17，且整个生态系统迁移到了Jakarta EE 9+。这意味着所有依赖javax.*的库都必须更换版本，否则运行时会出现ClassNotFoundException或NoClassDefFoundError。例如，springfox已经停止维护，其最后版本3.0.0只支持Spring Boot 2.x，如果升级到3.x后还保留springfox，应用启动就会报错。这时就需要把swagger相关依赖替换为springdoc-openapi 2.x版本，同时调整配置注解。类似的情况还有Hibernate Validator、Tomcat、Jackson等，虽然Spring Boot的依赖管理已经帮你锁定了一部分版本，但自定义的第三方依赖仍需要手工升级。

手动识别这些依赖非常依赖个人经验，尤其在一个包含几十个模块的微服务项目中，任何遗漏都可能导致生产事故。而自动化工具的核心价值在于：它们内部维护了与Spring Boot 3兼容的依赖版本映射表，能够快速比对项目中的现有依赖并给出精确的修改建议。更重要的是，这些工具还能处理依赖树传递冲突、属性变量引用（如${mybatis.version}）甚至Gradle的版本目录（Version Catalog）等复杂场景。接下来介绍三种主流的自动化方案。

使用OpenRewrite扫描并改写依赖版本

OpenRewrite是一个源代码和构建文件的重构引擎，它提供了一系列“recipe”来执行确定性修改。在Spring Boot升级场景中，有一个官方recipe叫做org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0，它可以自动完成很多迁移步骤，包括依赖版本更新、Java包替换、配置属性调整等。这个recipe会扫描你的pom.xml或build.gradle，把spring-boot-starter-parent、spring-boot-dependencies的版本改为3.x，并且处理像springdoc-openapi、thymeleaf-extras-springsecurity6、ehcache等常用库的版本升级。

要使用OpenRewrite，最简单的办法是在项目根目录执行Maven或Gradle命令。以Maven为例，在命令行运行：

mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \
  -DactiveRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0

执行后，OpenRewrite会分析项目的依赖树，将spring-boot版本从2.7.x改为3.0.x，同时把springdoc-openapi-ui从1.6.x升级到2.1.x，把hibernate-validator版本调整到8.x等。如果你使用了Gradle，可以添加rewrite-gradle-plugin并配置相同recipe。需要注意的是，OpenRewrite对依赖的修改是启发式的，它不会处理所有第三方库，但覆盖面已经很广。对于未被覆盖的库，它会标记出来，你仍然需要手动检查。

除了官方recipe，OpenRewrite社区还提供了很多针对特定库的迁移规则。例如，如果要迁移使用springfox的Swagger配置，可以额外激活org.openrewrite.java.spring.boot3.Swagger2ToSpringDoc2这个recipe，它会帮你把@EnableSwagger2注解替换为@EnableOpenApi，把Docket配置转换为OpenAPI Bean定义。这些recipe可以叠加使用，大幅减少手动迁移工作量。

另一个优点是OpenRewrite的“dryRun”模式。你可以在正式修改前加上-Drewrite.dryRun=true参数，它会生成一个patch文件而不会实际修改源码，让你先审查改动内容，确认无误后再执行真实变更。这在生产项目升级中非常有用。

利用Spring Boot Migrator针对特定组件迁移

Spring Boot Migrator（简称SBM）是Spring官方实验性项目，专门用来帮助开发者从Spring Boot 2.x迁移到3.x。与OpenRewrite的通用性不同，SBM更专注于解决特定技术栈的迁移痛点，比如将Swagger 2迁移到springdoc-openapi 2、将Ehcache 2/3的XML配置转换为Java配置、将MyBatis升级到Jakarta兼容版本等。SBM使用OpenRewrite作为底层引擎，并封装了更多针对性recipe。

使用SBM有多种方式，最灵活的是通过其Maven插件。在pom.xml中加入如下插件配置：

<plugin>
  <groupId>org.springframework.experimental</groupId>
  <artifactId>spring-boot-migrator-maven-plugin</artifactId>
  <version>0.15.0</version>
  <configuration>
    <recipes>
      <recipe>sbm:boot-3.0-upgrade</recipe>
    </recipes>
  </configuration>
</plugin>

然后执行mvn spring-boot-migrator:apply即可启动迁移。SBM会先扫描项目，识别出当前使用Spring Boot 2.x的特性和依赖版本，然后依次执行迁移步骤。例如，如果检测到项目里有springfox-swagger2依赖，它会自动移除该依赖并添加springdoc-openapi-starter-webmvc-ui:2.x，同时修改相关的Java配置类。对于使用了Ehcache的项目，SBM能够将ehcache.xml中老的配置格式转换为Spring Boot 3支持的JCache或Ehcache 3 Java配置，避免因为命名空间变化导致的启动失败。

从实践来看，SBM的迁移报告非常详细，它会列出每条recipe的执行状态、修改了哪些文件、还有哪些需要手工干预。这对于理解迁移范围非常有帮助。不过SBM目前仍然处于活跃开发阶段，版本迭代较快，使用时建议锁定一个稳定版本并先在测试分支验证。另外，SBM对Maven项目的支持优于Gradle，Gradle用户可能需要结合其他工具。

将自动化升级嵌入CI流水线实现持续维护

一次性升级完成后，并不意味着依赖版本问题彻底解决。随着Spring Boot 3的后续小版本发布（如3.1、3.2），新的兼容性问题还会不断出现。为了持续保持依赖健康，可以把自动化升级工具集成到CI/CD流水线中。常用做法是使用Dependabot或Renovate这类依赖更新机器人，它们会定期扫描项目依赖并提交Pull Request（PR），自动将过时的依赖升级到兼容版本。

以GitHub上的Dependabot为例，在仓库根目录添加.github/dependabot.yml文件，配置如下：

version: 2
updates:
  - package-ecosystem: "maven"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "org.springframework.boot"
        versions: ["2.x"]
    open-pull-requests-limit: 10

这个配置告诉Dependabot每周检查一次Maven依赖，并自动为超出Spring Boot 2.x范围的依赖创建升级PR。你可以指定忽略规则，避免它把Spring Boot主版本再降回2.x。提交PR后，CI流水线中的自动化测试会验证升级是否安全，通过后即可合并。这种方式让依赖升级从“一次性大工程”转变为“持续小步快跑”，风险更低。

此外，Renovate比Dependabot更灵活，它支持自定义规则、分组批量升级、甚至直接在PR中运行OpenRewrite recipe。例如可以配置Renovate在发现spring-boot新版本时，自动触发一次OpenRewrite扫描并连同代码修改一起提交。这种组合拳能够把依赖版本更新和代码适配完全自动化，特别适合微服务架构下大量模块的升级维护。

总结来说，Spring Boot 3升级中的依赖版本自动化识别与更新，有OpenRewrite、SBM、Dependabot/Renovate等多种工具可选。将它们组合起来，可以显著降低升级难度，减少人工排查时间。建议在正式升级前先在一个分支上运行这些工具的dry-run，仔细审查改动，再逐步推进到主分支。

Spring Boot 3依赖版本更新自动化升级修改时间：2026-09-23 19:47:12