SpringBoot2 升级 SpringBoot3 踩坑实录：一场“看似简单，实则重构”的升级战争

很多团队在看到：

xml 复制代码

<spring-boot.version>3.x.x</spring-boot.version>

的时候，会以为：

"不就是升个版本吗？"

真正开始升级之后才发现：

这不是一次普通升级。

而是：

Java 技术栈近几年最大的一次生态迁移。

尤其是中大型项目。

很多项目：

Boot2 跑了几年
微服务一大堆
Apollo/Nacos/Groovy/MyBatis/Dubbo/JPA 混搭
一堆历史 starter
一堆反射代码

升级到 Boot3 后：

各种诡异问题会开始爆炸。

本文结合真实踩坑经验，聊聊：

SpringBoot2 → SpringBoot3 到底会踩哪些坑。

一、先说本质：Boot3 不是"小版本升级"

很多人最大的误区是：

text 复制代码

2.x -> 3.x

看起来只是：

text 复制代码

版本 +1

实际上：

Boot3 = Spring Framework 6 + Jakarta EE 9 + Java17

它背后意味着：

变化	影响级别
Java17 强制要求	巨大
javax 全面迁移 jakarta	巨大
Spring6 底层重构	巨大
Tomcat10 升级	巨大
Hibernate6 升级	巨大
AOT/Native 支持	中等
PathPatternParser 默认启用	中等
Security 配置方式改变	巨大

所以：

很多"原来能跑"的代码，现在会直接炸。

二、第一个大坑：javax 全部变 jakarta

这是 Boot3 最大核弹。

例如：

以前：

java 复制代码

import javax.servlet.Filter;
import javax.annotation.Resource;
import javax.validation.Valid;

Boot3：

java 复制代码

import jakarta.servlet.Filter;
import jakarta.annotation.Resource;
import jakarta.validation.Valid;

三、最容易忽略的坑：@Resource 失效

这是很多老项目升级后最诡异的问题。

表现：

text 复制代码

Bean 明明存在
但@Resource 注入失败

尤其：

Apollo
Groovy 动态 Bean
自定义 BeanFactory
多 ClassLoader 场景

特别容易出现。

原因

很多项目还在使用：

java 复制代码

import javax.annotation.Resource;

但：

Boot3 已经不再支持 javax.annotation

必须改成：

java 复制代码

import jakarta.annotation.Resource;

更坑的是：

IDEA 有时候不会报错。

因为：

项目里可能残留：

xml 复制代码

javax.annotation-api

导致：

编译通过
运行异常
Bean 注入失败

这类问题非常阴间。

四、第二个核弹：Java17 强制要求

Boot3 最低要求：

Java17

很多老项目会炸：

反射
Unsafe
字节码增强
Groovy
CGLIB
Agent

常见报错

例如：

text 复制代码

Unable to make field private final accessible

或者：

text 复制代码

InaccessibleObjectException

原因

Java17 开始：

JDK 模块化封装更严格。

很多以前偷偷反射 JDK 内部类的代码：

现在直接禁止。

解决方案

临时方案：

bash 复制代码

--add-opens java.base/java.lang=ALL-UNNAMED

但：

这只是续命。

长期一定要升级依赖。

五、第三个巨坑：Spring Security 配置全部失效

以前：

java 复制代码

extends WebSecurityConfigurerAdapter

Boot3：

直接废弃。

新写法

现在必须：

java 复制代码

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    return http.build();
}

很多团队升级后：

会出现：

登录失效
接口403
JWT过滤器不生效
跨域失效

因为：

Security 配置体系已经完全重构。

六、PathPatternParser 巨坑

Boot2 默认：

text 复制代码

AntPathMatcher

Boot3 默认：

text 复制代码

PathPatternParser

于是：

很多路径匹配突然失效。

例如：

java 复制代码

/**/*.js

可能行为变化。

常见现象

text 复制代码

接口404
静态资源失效
Swagger打不开

解决方案

临时兼容：

yaml 复制代码

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

但：

不建议长期依赖。

因为未来可能彻底移除。

七、Hibernate6 升级是灾难区

Boot3 默认：

Hibernate6

这会导致：

SQL 行为变化
方言变化
分页异常
类型映射变化

经典问题

例如：

text 复制代码

Could not resolve attribute

或者：

text 复制代码

SQLGrammarException

原因

Hibernate6：

对 JPQL 校验更严格了。

以前很多"能跑但不规范"的 SQL：

现在直接报错。

八、MyBatis 项目也别高兴太早

虽然 MyBatis 比 JPA 稳。

但：

Boot3 下：

PageHelper
通用 Mapper
老 starter

都可能兼容性炸裂。

尤其：

很多 starter：

xml 复制代码

mybatis-spring-boot-starter

版本过低时：

会直接启动失败。

九、Apollo / Nacos 是高危区

这是很多公司最容易翻车的地方。

Apollo

很多版本：

根本不兼容 Boot3。

尤其：

text 复制代码

apollo.bootstrap.enabled

行为可能变化。

常见问题

Bean 提前初始化失败
配置未注入
@Value 为空
自动装配失效

原因

Spring6：

Bean 生命周期细节变化了。

很多旧 starter：

BeanPostProcessor
EnvironmentPostProcessor
BootstrapContext

已经不适配。

十、Dubbo 升级也容易炸

很多老 Dubbo：

依赖 javax
依赖老 Spring
SPI 行为变化

升级后：

消费者/provider 会出现各种奇怪问题。

特别是：

text 复制代码

GenericService

十一、最容易被忽略的问题：第三方生态根本没准备好

很多团队以为：

text 复制代码

我代码改完就行

实际上：

真正的问题是生态。

你会发现：

很多依赖：

2年没更新
作者失踪
不支持 jakarta
不支持 Java17

于是：

你会进入：

"依赖地狱"

十二、Groovy 是重灾区

很多动态规则系统：

升级后会遇到：

text 复制代码

import 失效
类加载异常

原因

Java17 + Spring6：

类加载机制更严格。

尤其：

多 ClassLoader
动态编译
热加载

特别容易出问题。

十三、为什么很多团队升级周期长达几个月

因为：

真正耗时间的不是：

text 复制代码

改代码

而是：

排查生态兼容性。

十四、正确升级姿势（非常重要）

很多团队：

text 复制代码

直接改 Boot 版本

然后项目爆炸。

正确步骤应该是：

第一步：先升级 Java17

先确保：

Boot2 + Java17 能稳定运行。

第二步：升级第三方依赖

例如：

Apollo
Nacos
Dubbo
MyBatis
Elasticsearch
RocketMQ

先确认：

是否存在 Boot3 兼容版本。

第三步：处理 javax → jakarta

这个可以：

全局替换。

但：

一定要谨慎。

第四步：升级 SpringBoot3

最后才：

xml 复制代码

spring-boot 3.x

十五、升级过程中最重要的原则

不要"一次性升级全部"。

很多团队：

Java8 → 17
Boot2 → 3
SpringCloud 全升级
中间件全升级

一起做。

结果：

根本无法定位问题。

十六、一个非常实用的建议

做"双环境灰度"

例如：

老版本继续跑
新版本旁路验证
流量灰度切换

否则：

生产事故概率极高。

十七、Boot3 最大的收益是什么？

虽然踩坑很多。

但：

升级后收益也很明显。

1. Java17 性能更好

尤其：

G1
ZGC
字符串
CDS

都有提升。

2. Spring6 更现代化

例如：

AOT
Native
更好的 Observability
Micrometer 深度整合

3. 云原生支持更好

Boot3：

明显更偏：

Kubernetes 时代。

十八、最后总结一句

很多人觉得：

"升级 SpringBoot3 是技术工作。"

其实不是。

真正难的是：

"整个 Java 生态正在集体迁移。"

Boot3 本质上：

不是一个框架升级。

而是：

Java 世界从旧时代进入新时代的分水岭。

如果你的项目：

历史久
依赖多
自定义多
动态能力多

那么：

这次升级，几乎等于一次系统级体检。

但反过来说：

能顺利完成 Boot3 升级的团队。

通常：

工程治理
依赖治理
技术债管理

都会明显提升一个层级。