Spring Boot 4 升级复盘

发表于 2026-04-20 更新于最近

作者 Eric

33~42 分钟 阅读

见字如面，与大家分享实践中的经验与思考。

当我看到最新框架 Spring Boot 4 中支持注解声明、开箱即用的 API Versioning 功能的时候，对于多端项目来说，简直就是福音，就开始计划将项目都从 Spring Boot 3 升级到 Spring Boot 4。开始阅读官方的各种文档，评估项目升级可能带来的问题，因为我知道：

框架大版本升级，本质上不是一次版本替换，而是一次基础设施层的重新校准。

如果是之前的话，我会去搜迁移文档、改报错、修编译，按照这个思路慢慢改，但是这次我采用 AI 辅助的方式，从产出方案评估、迁移计划、落地实施、关键路径验证清单等一系列流程，半小时不到就完成生产丝滑的迁移和验证。

现在已经在生产环境运行运行了大半个月了，如果你也准备从 Spring Boot 3 迁到 4，这些方向和思路比某个具体类名怎么改，更具有价值。

images-20260419-18.22.35@2x

Spring Boot 4 核心重要升级

先来看下 Spring Boot 4 这次值得关注的更新有哪些，是项目是否选择升级的重要一步。以下是我结合结合官方发布说明、Release Notes 和 Migration Guide，认为有几个点最值得先关注：

整体技术基线上移：Spring Boot 4 基于 Spring Framework 7，要求 Java 17+，同时支持 Java 25，并建立在 Jakarta EE 11 和 Servlet 6.1 基线之上。对于老项目来说，这意味着升级不再只是框架替换，而是运行时和依赖体系都要一起看。
代码库进一步模块化：Spring Boot 4 对代码库做了更完整的 modularization，目标是让 jar 更小、职责更聚焦。这会影响后续依赖组合、自动配置边界以及项目对 Boot 内部模块的感知方式。其中 Jackson 的包变化最大。
API Versioning 成为一等能力：Spring Boot 4 为 Spring MVC 和 WebFlux 提供了 API Versioning 自动配置支持。对于需要长期维护多个 API 版本的系统来说，这算是一个很实用的官方能力补齐。
HTTP Service Clients 得到官方支持：Spring Boot 4 新增了对 HTTP Service Clients 的自动配置支持，可以基于带注解的 Java 接口生成客户端实现。这个方向很适合替代一部分手工封装的远程调用样板代码。
Observability 继续增强：官方新增了 spring-boot-starter-opentelemetry，用于导出 metrics 和 traces，并自动配置 OpenTelemetry SDK。对于已经在做链路观测、指标采集和 tracing 的系统来说，这一块会比过去更顺手。
测试与基础设施能力继续补齐：对 RestTestClient、JMS 新 API、Redis observability、任务装饰器组合等能力的增强。这些不一定每个项目都会立即用到，但能看出来 Boot 4 在继续补齐“工程化细节”。

简单来说，Spring Boot 4 不只是一次常规升级，它更像是把 Web、观测、客户端调用、测试和底层依赖一起往新一代 Spring 技术栈上统一收口。

如果你想先系统看完 Spring Boot 4 的完整变化，再回来看这篇实战，建议直接读下面这几份官方材料：

官方发布说明：适合先快速了解 Spring Boot 4 整体更新范围（https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes）
官方迁移指南：适合升级前逐项核对兼容性变化（https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide）
官方发布博客：适合先建立对新版本定位和变化重点的整体认知（https://spring.io/blog/2025/11/20/spring-boot-4-0-0-available-now）

实战

本人项目是从 SpringBoot 3.5.11 和 Gradle 9 进行升级的。如果要人肉看官方文档一步步修改，本人是不建议升级的，这也是很多公司到现在还在用 JDK 8 / JDK 11 的原因，因为牵一发而动全身，我用 AI 操作一遍，才知道要修改的地方有这么多，有些地方你都无法想到，这还是项目是我从零开始架构的，时间太长很多配置自己都忘记了，何况团队开发的呢。

接下来我将讲解如何使用 AI 进行平滑的迁移。

01 确定升级清单

以下是我整理出来的 AI 基础提示词，输出的迁移计划最完整，最合理，并且能够形成闭环。

我需要将一个现有项目从 Spring Boot 3.5.11 升级到 Spring Boot 4.0.5。请基于 Spring 官方最新文档，并结合当前项目的实际代码与配置，输出一份可执行的完整迁移升级计划，至少包含如下部分：
- 1. 升级 SpringBoot 主版本到 4.0.5
- 2. 切换到 SpringBoot 4 最新的 Starter 体系
- 3. 替换 SpringBoot 3 专用的的三方 Starter
- 4. 修复 SpringBoot 4 带来的包路径变化
- 5. 适配 Jackson 3、WebMVC、Security 等关键组件
- 6. 检查自定义 Spring Bean 配置
- 7. 基础 foundation 包中各种模块的 SpringBoot 4 兼容性检查（可选）
- 8. 输出升级后的验证清单，确认关键行为是否正常

通过以上提示词，可以看到一条主线：先确定范围 -> 再处理依赖和 Starter -> 接着处理 JSON、Web 与认证链路 -> 然后补齐公共模块 -> 最后验证关键行为。

如果顺序乱了，升级就会被各种细节报错拖着走；如果顺序对了，很多复杂问题反而会自然收敛。

重要的一点，就是请选择顶级的模型执行！要有 Web Search 能力，还要结合 CLAUDE.md 或者 AGENTS.md 帮助 AI 快速了解项目的上下文，快速定位项目目录和文件。可以参考我之前的文章：一套可落地的企业级 AGENTS.md 项目规则实践

02 关键链路验证

如果你的项目里有 foundation、common、starter、platform 这类共享模块，最后一定要回头把它们单独检查一遍。因为很多升级问题其实不是出在主工程，而是出在这些平时不常改的公共层里。

这里建议重点检查两类内容：

自动配置注册文件是否还生效
共享模块里的 compileOnly / optional 依赖是否也切到了 SpringBoot 4 体系

最后验证时，不要只停留在“编译通过”，至少把下面几类行为过一遍：

核心接口请求是否正常
参数绑定和返回格式是否正常
登录、鉴权、刷新 token 是否正常
定时任务、缓存、锁等基础能力是否正常
数据访问和事务行为是否正常

如果有自动化测试，就让自动化测试帮你守住这一步；如果暂时没有，也至少要手工跑一遍最关键的业务路径。升级做到这里，才算真正结束。

03 执行过程中的坑

绝大部分升级问题，AI 都能帮你解决，但是部分冲突代码，还是需要人工解决的，我这里讲几个例子：

1）坑一：

SpringBoot 4 默认基于 Jackson 3，改为最新的包路径即可，但如果项目有自定义的 ObjectMapper Bean 的话，需要移除或者采用 JsonMapperBuilderCustomizer 进行调整，因为 SpringBoot 4 下 ObjectMapper 已经由 SpringBoot 自动创建，而且它会带上一整套自动配置能力。你这里如果再手工注册，就会出现两套同类型 Bean 并存，启动时会报 NoUniqueBeanDefinitionException 错误。

但是又想要一个工具类的话，建议按照如下处理：

images-20260419-18.02.59@2x