问问助手

依赖没理顺,Spring Boot 4 先别急着上

2026-09-24 Aryee 23

Spring Framework 7.0.0 在 2025 年 11 月 13 日发布,Spring Boot 4.0.0 一周后的 11 月 20 日跟上。到现在已经有若干维护版本,是可以正经讨论迁移的时点了。

先说结论:这次升级的难度不在新特性,在一堆改名和删除。这些改动不会让代码写不出来,但会让构建在半途崩掉,或者启动时缺一整类自动配置。

下面按「编译时能发现」和「跑起来才发现」两类分开列,这个分法决定了你能不能在自动构建里就把活干完。

一、Java 门槛其实没抬

很多人以为 Boot 4 抬了 Java 门槛,其实没有。官方说法是 Framework 7 保留 JDK 17 基线,同时推荐 JDK 25 作为最新长期支持版。Boot 侧的系统要求页面写得更具体。

项 要求
Java 17 最低,官方说明支持到 Java 26
Spring Framework 7.0 这一档的较新维护版(Boot 的系统要求页给了最低值)
Jakarta EE 11 基线
Servlet 容器 Servlet 6.1+(Tomcat 11.0.x / Jetty 12.1.x)

表里没列的那几项,包括 Maven、Gradle、GraalVM、Kotlin 的最低版本,每出一个维护版都可能往上抬一档。

动手前用你自己那套构建工具实测一次,别照抄任何一篇文章里的数字。

二、真正挡路的是 Jakarta EE 11 和 Servlet 6.1

内嵌容器(也就是和应用打在一个包里的那套运行环境)要跟着换版本。Servlet 容器之外的东西,包括安全框架的过滤链、老的监控探针、任何直接实现 javax.servlet 类型的组件,都得确认是否已经有 jakarta.servlet 版本。

如果你的技术栈里还有 Spring Security 5 时代的东西或者第三方 servlet filter,这一项的优先级高于 Boot 本身。

三、starter 改名:构建阶段第一道坎

Boot 4 把一批 starter 换成了更规范的名字。

旧 新
spring-boot-starter-web spring-boot-starter-webmvc
spring-boot-starter-oauth2-client spring-boot-starter-security-oauth2-client
spring-boot-starter-oauth2-resource-server spring-boot-starter-security-oauth2-resource-server
spring-boot-starter-oauth2-authorization-server spring-boot-starter-security-oauth2-authorization-server
spring-boot-starter-web-services spring-boot-starter-webservices

WebFlux 也拿到了自己的专用 starter。

四、旧名字不会给你一条清晰的报错

这件事的麻烦不在改名本身,在于旧名字不会给你一条清晰的报错。依赖解析不到,构建失败,但错误信息指向的是坐标,不是你该换成哪个。

所以正确做法是先在依赖树里把 spring-boot-starter- 开头的项全部导出来,逐个对照,而不是等 Maven 一条条报。

五、内嵌启动脚本的支持被移除了

内嵌的启动脚本支持被移除,就是让 jar 文件自己能当脚本跑、省掉 java -jar 的那层封装。

如果你的部署方式走的正是那条路,这一项要提前确认。改法无非是回到 java -jar,或者自己出一版启动脚本。

六、Jackson 3 换了包名,这是最大的工程量

Framework 7 和 Boot 4 把 Jackson 3 作为默认,而 Jackson 3 换了 Maven 坐标和 Java 包名:从 com.fasterxml.jackson 变成 tools.jackson。

这意味着所有 import 都要改,包括那些写了 TypeReference、ObjectMapper、注解的类。代码量大一点的项目,这一步的改动量会比整个升级剩下的部分加起来都大。

七、Jackson 2 可以和新默认并存

com.fasterxml.jackson.annotation 这一组的包名没变,注解类不用动。

Jackson 2 仍然支持,但要显式引 spring-boot-jackson2 模块。这是这次迁移里最有价值的一条退路:如果你的依赖树里有某个库死咬 Jackson 2,比如老版 SDK、某些序列化组件,不必强推那个库升级,可以让 Jackson 2 和新默认并存一阵。

Boot 侧的 @JsonComponent 改名为 @JacksonComponent。这类自己写的定制组件容易漏,因为这类组件不在依赖里、只在源码里。

我的建议顺序:先把 Jackson 2 与 3 并存的边界画出来,再动手改 import。反过来做的话,中途一定会碰到「这个库不支持 Jackson 3」。那时已经改了一半,退回去的成本比当初多引一个模块高得多。

八、测试注解的替换

@MockBean 和 @SpyBean 换成 @MockitoBean 和 @MockitoSpyBean,包路径也换了。

测试基类里写了这两个注解的,全项目替换即可,但要注意新注解的作用范围有调整。旧的那个是类级别注册,新的要留意重复声明的行为。别只做完文本替换就认为等价。

九、Spock 支持被移除

还在用 Groovy 和 Spock 写集成测试的团队,这一项是选择题而不是改造题:迁到 JUnit,或者停在 Boot 3 上不动。

十、跑起来才暴露的第一件事:探针默认开启

Actuator 的存活与就绪探针默认开启。这在 Kubernetes 上是好事,但另一面是端口上的探测端点从「你不配就没有」变成了「默认就在那儿」。

如果服务在集群外可路由,或者运维网络策略是按「这些路径不存在」的前提配的,升级等于悄悄新增了一个公开端点。

升级前先确认 8081(或你合并到主端口的那个 actuator 端口)的实际暴露面。

十一、第二件:配置加载接口换了包

EnvironmentPostProcessor 换了包,到了 org.springframework.boot。

这是 SPI:靠 spring.factories 或 AutoConfiguration.imports 注册的实现类,包名写错不会编译失败,只会静默不生效。

自定义过配置加载逻辑的项目,要显式验一次它有没有被调用。最直接的方式是在里面打一条日志,确认它出现在启动输出里。

十二、第三件:MongoDB 配置项前缀改了

MongoDB 配置项前缀改成 spring.mongodb.*。属性改名是「删掉不报错、写错不报错」的一类,只在连不上时才发现。

凡是自管配置中心里存了这些 key 的,而不是写在 application.yml 里能靠 IDE 补全看出问题的,要单独在配置中心做一次全量搜索。

十三、第四件:静态元模型生成器换了

JPA 静态元模型生成器换成 hibernate-processor。构建插件里引的 hibernate-jpamodelgen 要换掉,否则 JMetaModel 不再生成。

运行期 Criteria 查询报的是「找不到静态元模型属性」这类间接错误。

十四、值得主动用的两条

HTTP 接口客户端。Framework 7 对「声明式 HTTP 接口 + 多个目标主机」的配置做了专门支持。如果你手上还有一堆手写 WebClient 调用外部服务的代码,这一块可以省掉不少样板,同时把超时、重试的位置统一起来。

框架自带的重试支持。org.springframework.core.retry 让框架层有了基础重试抽象,不必为了三次重试再引一个第三方库。

十五、两条没有证实的传闻

网上流传的「Boot 4 强制要求编译加 -parameters」「@ConstructorBinding 已移除」这两条,迁移指南和系统要求页上都没有对应表述,所以按未证实处理。

判断依据仍以官方迁移指南为准。

十六、一条迁移顺序

  1. 先在 Boot 3.x 上把废弃 API 清零。这一步单独做,做完能跑、能回退。它能把后面所有报错的范围缩小到「Boot 4 独有的问题」。
  2. 画 Jackson 边界:列出依赖树里所有会拉进 Jackson 2 的项,逐个确认有没有 Jackson 3 兼容版本。这一步的产出是一份清单,不产代码。
  3. 换构建坐标、改 import,让项目能编译。这一步改动最大,也最容易评审疲劳,所以要单独一个 PR,不要混任何业务改动。
  4. 容器与 Servlet 层验证:Tomcat 11 和 Jetty 12.1 起一遍,重点看 filter、listener 和会话相关行为。
  5. 专门过一遍上面那四条「跑起来才暴露」的,尤其是 SPI 与配置中心里的 key。

第 3 步和第 5 步之间留几天,不要连着做。这个升级里最难查的问题,都发生在「编译过了、启动也正常、但某个静默失效的组件第一次被调用」的时刻。

十七、最后一句

升级的难点从来不是学新写法,而是把旧名字、旧坐标、旧默认值一处不漏地找出来。

清单列得越细,真到动手那天越省力。

引用这一篇
https://www.aryee.cn/archives/spring-boot-4-migration.html

转载或引用请注明出处与链接。

你手上那套系统,卡在哪一步?

留个手机号和方便的时间,我打过来先听你说现状和限制,再给一个能执行的判断:这套系统该继续修、该动哪里,还是重做一版更省。

约一次沟通不接纯 UI 外包,只做系统层面的问题。不方便留号码,也可以直接跟助手说一句话。