SpringBoot 2.x到3.x升级实战与经验分享
作者：乐悠厨房
1. 项目背景与升级必要性
Spring Boot从2.x到3.x的跨越式升级，本质上是一次技术架构的重大演进。作为长期维护Spring Boot 2.7.18项目的技术负责人，我最初对升级持保守态度——直到发现官方将在2023年11月停止对2.7.x的维护支持。这意味着继续使用旧版本将面临安全漏洞无人修复的风险，这才促使团队下定决心进行技术升级。
这次升级的核心挑战在于：Spring Boot 3.x最低要求JDK 17，而我们的生产环境仍运行在JDK 8上。更棘手的是，Jakarta EE 9+的命名空间变更（从javax. 到jakarta. ）导致大量依赖库需要同步更新。经过两周的攻坚，我们最终成功将整套系统迁移到Spring Boot 3.5.8，过程中积累的经验值得与各位同行分享。
2. 升级前的准备工作
2.1 环境兼容性检查清单
在开始升级前，必须完成以下环境审计：
- JDK版本：确认本地和CI环境都已安装JDK 17（推荐Azul Zulu 17.0.8）
- IDE支持：IntelliJ IDEA需要2021.3+版本才能完全兼容Spring Boot 3.x
- 构建工具：Gradle 7.5+或Maven 3.6.3+（建议使用Gradle的版本目录功能管理依赖）
- 数据库驱动：MySQL Connector/J需要8.0+，PostgreSQL JDBC需要42.3.0+
重要提示：千万不要在生产环境直接尝试升级！建议使用Docker创建隔离的测试环境，镜像可参考：
FROM eclipse-temurin:17-jdk-jammy RUN apt-get update && apt-get install -y maven
2.2 依赖库影响评估
使用mvn dependency:tree或gradle dependencies生成依赖树，重点关注这些易出问题的库：
| 依赖类型 | 2.x版本 | 3.x适配版本 | 变更说明 |
|---|---|---|---|
| 持久层 | spring-data-jpa 2.7.x | 3.0.x | 方法签名变更 |
| 文档 | springfox 3.0.0 | springdoc-openapi 2.1.0 | 完全重写 |
| 安全 | spring-security 5.8.x | 6.1.x | 配置方式变更 |
| 模板 | thymeleaf 3.0.x | 3.1.x | 方言注册方式变化 |
3. 分步升级实操指南
3.1 基础框架升级步骤
- 修改pom.xml/gradle.build中的父POM：
<!-- 原配置 -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.18</version>
</parent>
<!-- 新配置 -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.0.8</version> <!-- 建议先升到3.0.x再逐步到3.5.8 -->
</parent>- 处理Jakarta命名空间变更：
# 使用OpenRewrite进行自动化迁移（需Java 17环境运行） mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \ -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:LATEST \ -Drewrite.activeRecipes=org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0
- 特别处理Hibernate 6.x的变更：
// 旧版配置
@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
// ...
properties.put("hibernate.dialect", "org.hibernate.dialect.MySQL5Dialect");
}
// 新版配置
@Bean
public LocalContainerEntityManagerFactoryBean entityManagerFactory() {
// ...
properties.put("hibernate.dialect", "org.hibernate.dialect.MySQLDialect"); // 移除版本号
}3.2 常见组件适配方案
3.2.1 Spring Security 6.x适配
最重大的变更来自CSRF保护机制的调整：
// 旧版配置 http.csrf().disable(); // 新版配置 http.csrf(csrf -> csrf.disable()); // Lambda DSL风格
3.2.2 文档工具迁移
从Springfox迁移到springdoc-openapi的配置示例：
@Configuration
public class OpenApiConfig {
@Bean
public OpenAPI customOpenAPI() {
return new OpenAPI()
.info(new Info().title("API文档")
.version("3.0")
.contact(new Contact().name("团队")));
}
}
4. 疑难问题排查实录
4.1 典型编译错误解决方案
问题1：javax包找不到
错误: 程序包javax.servlet不存在
解决方案：
- 检查是否漏掉了jakarta.servlet:jakarta.servlet-api依赖
- 使用IDE的全局替换功能（Ctrl+Shift+R）将javax. 改为jakarta.
问题2：Hibernate懒加载异常
org.hibernate.LazyInitializationException: could not initialize proxy
解决方案：
# 在application.properties中增加： spring.jpa.properties.hibernate.enable_lazy_load_no_trans=true
4.2 运行时异常处理
问题3：Actuator端点404
curl http://localhost:8080/actuator/health # 返回404
解决方案：
management:
endpoints:
web:
exposure:
include: "*"
endpoint:
health:
show-details: always5. 升级后的验证策略
5.1 自动化测试保障
建议在CI流水线中加入以下检查项：
# GitHub Actions示例
jobs:
verify:
steps:
- run: mvn test -Dspring.profiles.active=test
- run: |
curl -sSf http://localhost:8080/actuator/health | \
jq -e '.status == "UP"' || exit 15.2 性能基准测试
使用JMeter进行升级前后对比测试，重点关注：
- 平均响应时间变化（应<15%差异）
- GC暂停时间（JDK17的ZGC应该表现更好）
- 内存占用（建议使用VisualVM监控）
6. 回滚方案设计
尽管我们希望一次升级成功，但必须准备回滚方案：
- 代码回滚：Git tag标记发布版本
- 数据库备份：mysqldump全量备份
- 环境隔离：通过Docker网络隔离新旧版本服务
经验之谈：在实际操作中，我们采用了蓝绿部署策略，通过Nginx流量切换确保零停机回滚。配置示例：
upstream old {
server 192.168.1.10:8080;
}
upstream new {
server 192.168.1.20:8080;
}
server {
location / {
proxy_pass http://$target;
}
}
7. 升级后的优化建议
成功升级到Spring Boot 3.5.8后，可以考虑这些增强措施：
- 启用GraalVM原生镜像编译（需添加spring-boot-starter-native依赖）
- 迁移到Spring Security 6.1的新密码存储方案
- 试用Spring Boot 3.x新增的ProblemDetail错误响应标准
经过这次升级，我们的应用启动时间减少了23%，内存占用下降18%。最大的收获是终于可以放心使用Records、Text Blocks等JDK17新特性了。对于仍在犹豫是否升级的团队，我的建议是：越早开始迁移，技术债的利息就越低。
到此这篇关于SpringBoot 2.x到3.x升级实战与经验分享的文章就介绍到这了,更多相关SpringBoot 2.x到3.x升级内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！