1. SpringBoot大版本升级实战：从SpringBoot2到SpringBoot3
最近在将公司核心系统从SpringBoot2升级到SpringBoot3的过程中，踩了不少坑也积累了不少经验。这次升级不仅仅是简单的版本号变更，更涉及到JDK基线升级、依赖组件适配、API变更等一系列连锁反应。下面我就把整个升级过程中的关键点和解决方案整理出来，给准备升级的同行们参考。
SpringBoot3作为2022年底发布的重要版本，最大的变化就是要求JDK17作为最低版本支持。这意味着我们不仅需要升级框架本身，还需要同步升级整个开发环境和运行时环境。从实际升级效果来看，新版本在性能优化、GraalVM原生镜像支持等方面都有显著提升，但升级过程确实需要做好充分准备。
2. 升级前的准备工作
2.1 环境要求确认
SpringBoot3.x系列最低要求JDK17，这意味着：
- 开发环境需要安装JDK17（建议使用LTS版本）
- 构建工具需要支持JDK17（Maven 3.5+或Gradle 7.x+）
- CI/CD环境需要预先配置好JDK17运行环境
- 生产服务器需要预先安装JDK17
注意：如果你的项目还在使用JDK8，建议先单独升级到JDK17并确保系统稳定运行，再进行SpringBoot升级。
2.2 依赖组件兼容性检查
SpringBoot3带来的变化会影响大量相关组件，需要重点检查：
- 持久层框架：MyBatis 3.5+, Hibernate 6.1+
- 数据库连接池：HikariCP 5.0+
- 缓存组件：Redis客户端需要最新稳定版
- 消息队列：Kafka/ActiveMQ等客户端版本
- 其他第三方starter的兼容性
建议使用Maven的dependency:tree命令全面分析当前项目的依赖树，对照SpringBoot3的官方兼容列表逐一检查。
2.3 代码兼容性扫描
SpringBoot3中废弃和修改了不少API，需要重点关注：
- javax包迁移到jakarta（Servlet、JPA等）
- 配置属性的变更（特别是Spring Security相关）
- 自动配置类的变化
- 测试框架的调整
可以使用兼容性扫描工具如OpenRewrite来自动检测不兼容的代码：
xml复制<plugin>
<groupId>org.openrewrite.maven</groupId>
<artifactId>rewrite-maven-plugin</artifactId>
<version>4.38.0</version>
<configuration>
<activeRecipes>
<recipe>org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0</recipe>
</activeRecipes>
</configuration>
</plugin>
3. 实际升级步骤详解
3.1 修改POM文件
首先更新父POM和SpringBoot版本：
xml复制<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.1.0</version> <!-- 最新稳定版 -->
</parent>
<properties>
<java.version>17</java.version>
</properties>
然后逐一检查并更新所有SpringBoot相关的starter依赖，确保版本一致：
xml复制<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!-- 其他starter保持相同groupId和artifactId，版本由父POM管理 -->
3.2 处理javax到jakarta的迁移
这是最可能遇到问题的部分。所有javax.包的导入需要改为jakarta.，主要影响：
- Servlet API（Filter、HttpServletRequest等）
- JPA相关注解（@Entity、@Table等）
- Bean Validation注解（@Valid等）
可以使用IDE的全局替换功能，但要注意：
- 不要替换javax.annotation（如@Resource）
- 不要替换javax.inject（如@Inject）
- 注意XML配置文件中可能也有javax引用
3.3 配置属性调整
SpringBoot3中许多配置属性发生了变化，例如：
| 旧配置 | 新配置 |
|---|---|
| server.servlet.context-path | server.servlet.context-path |
| spring.datasource.hikari.connection-timeout | spring.datasource.hikari.connection-timeout |
| management.endpoints.web.exposure.include | management.endpoints.web.exposure.include |
建议在升级后启动时添加--debug参数，SpringBoot会输出所有废弃的配置属性警告。
4. 常见问题与解决方案
4.1 启动类扫描失败
错误示例：
code复制org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'
解决方案：
- 添加spring.mvc.pathmatch.matching-strategy=ant_path_matcher到application.properties
- 或升级SpringDoc OpenAPI到2.x版本
4.2 JPA实体类报错
错误示例：
code复制jakarta.persistence.EntityNotFoundException: Unable to find com.example.User with id 123
解决方案：
- 确保所有JPA注解从javax.persistence改为jakarta.persistence
- 检查Hibernate版本是否兼容（建议6.1+）
4.3 测试类失败
常见问题：
- @SpringBootTest找不到配置
- MockMvc测试失败
解决方案：
- 更新spring-boot-starter-test到3.x版本
- 检查测试配置中的过时API
- 对于MockMvc，更新import为org.springframework.test.web.servlet.MockMvc
5. 升级后的验证与优化
5.1 基础功能验证清单
- 应用启动是否正常
- 核心API是否可用
- 数据库连接是否正常
- 缓存功能是否生效
- 定时任务是否正常执行
- 监控端点是否可访问
5.2 性能基准测试
升级后建议进行简单的性能测试：
- API响应时间对比
- 内存占用对比
- 启动时间对比
- 并发能力测试
5.3 新特性利用
SpringBoot3值得关注的新特性：
- 改进的GraalVM原生镜像支持
- 增强的Micrometer观测能力
- 改进的问题诊断报告
- 更灵活的自动配置
6. 回滚策略与注意事项
尽管我们做了充分准备，升级仍可能出现意外情况。建议：
- 在低峰期进行升级
- 准备详细的回滚方案
- 保留旧版本的部署包
- 数据库变更要有回滚脚本
- 配置变更要记录详细差异
我在实际升级中发现，最大的挑战往往不是框架本身，而是各种第三方库的兼容性问题。建议采用渐进式升级策略：先升级JDK，再升级SpringBoot，最后处理依赖组件。对于大型项目，可以考虑模块化逐步升级，而不是一次性全量升级。