一、要不要迁：时间线先把这个问题定死

Spring Boot 3 的入门认知站内已有《Spring Boot 框架入门》打底，这一篇假设你已经写过 3.x 项目，只回答一个问题：3.x 到 4.x 这一跳，带来什么、破坏什么、怎么迁。先把时间线摊开，因为”要不要迁”不是靠感觉，是靠支持周期到期日定死的：

再看运行基线，好消息是这次没有强制搬家：

Java 基线留在 17 是这代升级最大的善意：上一跳（2.x 到 3.x）最疼的 javax 到 jakarta 迁移这代没有对应物，多数项目的工作量集中在”模块化拆分的连锁反应 + 弃用清理”两件事上——正好是下两节的主角。

二、模块化重构：带来什么

Boot 4 最大的结构性变化是把那块”什么都有”的 spring-boot-autoconfigure 巨型 jar 拆成了按技术粒度的一组模块——Web 服务器、数据访问、缓存、消息，各有各的自动配置模块（如 spring-boot-web-server-autoconfigure 这类命名）。官方博客的说法是”模块化 Spring Boot”，注意这里的”模块”指的是 jar 拆分，不是 JPMS（Java 平台模块系统），别被词吓到。

对普通应用开发者，这个拆分大部分被 starter 屏蔽了：starter 会替你声明它需要的自动配置模块，多数应用改个版本号就能编译。它真正改变的是两件事。第一，装配更可解释。以前排查”这个 Bean 从哪来的”要在一个巨型 jar 里翻；现在按技术分家，条件评估报告与源码组织对得上，排障时少一层迷雾。第二，依赖图更诚实。以前一个传递依赖就能把整块自动配置拖进来；拆分后，用了什么就声明什么，类路径上少一堆”不知道为什么在”的候选配置。

三、破坏什么：三类高频断裂点

断裂点一：spring.autoconfigure.exclude 里的类搬家了

3.x 里按完整类名排除自动配置的配置项，在 4.0 里会因为类迁入新技术模块而失效——失效方式是启动期找不到类，属于”一启动就炸”的友好型破坏。修法是把每个条目按官方迁移指南的对照表重定位；OpenRewrite / Moderne 提供了自动重定位这类条目的迁移配方，条目多的项目值得先跑一遍再人肉核对：

# application.yml / application.properties
1. 3.x 写法：按旧 FQN 排除
1. spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration
1. 4.0：类已迁入按技术命名的新模块，完整类名以官方迁移指南对照表为准，逐条重定位

断裂点二：自定义 starter 与三方 starter

这是拆分冲击最大的人群。3.x 时代写自定义 starter 有个普遍的隐性假设：classpath 上有 spring-boot-autoconfigure 这块”大杂烩”，自己的自动配置类随便引用其中任何类都编译得过。4.0 里这个假设作废——每个 starter 需要显式声明并依赖自己所属技术的那块自动配置模块。给团队内部框架的维护者列一张对照：

反模式一：靠传递依赖”顺带”拿到自动配置。4.0 下这是最典型的静默故障源——starter 编译通过、发布成功、使用方启动也成功，只是某个该自动装配的 Bean 没了，最后以 NoSuchBeanDefinition 的形式在离根因很远的地方爆出来。自定义 starter 在 4.x 下的纪律是：用哪块、声明哪块、测哪块。

断裂点三：3.x 生命周期内的弃用一次性全删

官方迁移指南的口径很硬：3.x 期间标记弃用的类、方法、属性，在 4.0 里全部移除，没有缓冲期。这意味着”在 3.5 上能编译过”不等于”在 4.0 上能编译过”——那些年你忽略掉的弃用告警，这一版集中结账。几个社区实测里高频命中的具体项：

四、Jackson 3：唯一建议”分两步”的项

Jackson 3 换了坐标（tools.jackson 命名空间）也改了一批默认行为，是这次升级里改动面最广的单项。好消息是官方明确支持 Jackson 2 与 3 共存，所以迁移策略可以解耦：先升 Boot 4、暂留 Jackson 2（显式声明 ObjectMapper 与消息转换器 Bean），让应用先跑起来；再单独开一个分支做 import 全局替换与默认行为对齐。一步到位当然也行，但把”框架升级”和”序列化行为变更”两件高风险事叠在同一次发布里，出问题时你分不清是哪边引入的。

五、内建 retry：少一个依赖，多一套语义

这代升级里少见的”净赚”项：Spring Retry 作为独立项目并进了 Framework 7 的 spring-core，@Retryable、RetryTemplate 成为框架原生能力，不用再单独引入 spring-retry 依赖，还附赠了并发闸门 @ConcurrencyLimit；注解用在返回 Mono/Flux 的方法上时，会自动改用 Reactor 的 retry 算子而不是阻塞式重试。示例：

@Service
public class InvoiceClient {

    // 注意语义：maxRetries 是"重试次数"，3 表示首次调用之外再试 3 次
    // 旧 spring-retry 的 maxAttempts 是"总尝试次数"，迁移时数字不能照抄，见下表
    @Retryable(maxRetries = 3)
    public Invoice fetch(String id) {
        // 调外部发票服务，失败由框架按注解重试
        return gateway.get(id);
    }

    // 并发闸门：同时只放行 10 个调用，超出的快速失败
    // 保护的是下游，也保护自己线程池——与 retry 同属这代的弹性能力包
    @ConcurrencyLimit(10)
    public void push(String id) {
        gateway.notify(id);
    }
}

反模式二：把 maxAttempts 的值原样搬给 maxRetries。旧值 4 表示”首次 + 3 次重试”，照抄成 maxRetries = 4 就变成 4 次重试，重试压力多一轮、超时窗口变长——这种错不报编译错误，只在下游故障时的报警曲线里现形。迁移时把项目里所有手写重试计数列出来逐个换算（maxAttempts 等于 maxRetries 加一）。

六、迁移步骤清单

顺序本身是正确性的一部分，别按喜好重排：

七、回归清单

八、诚实结论

这一跳的真实工作量分布：没有自定义/三方 starter 依赖、没有重度安全定制的小服务，多数是半天级——升版本、清弃用、跑回归；有内部 starter 的团队，工作量在 starter 侧而不是应用侧，且必须为”使用方静默装配缺失”准备专门的冒烟流程，预算按天算。判断顺序建议：先盘依赖矩阵（Spring Cloud、三方、内部 starter 有没有 4.x 线），再定排期——矩阵里任何一块没有 4.x 兼容版本，你单独迁主工程就是在制造一个起不来的分支。Java 语言侧配套的语法基线变化，可参见《Java 现代语法特性》。

版本核实（以官方文档为准）：Spring Framework 7.0 GA 于 2025-11-13、Spring Boot 4.0 于 2025-11-20 发布（spring.io 官方公告）；Java 基线 17 未升、Java 25 一等支持（官方公告口径）；4.0 开源支持至 2026-12-31（官方支持页），撰写时 4.1.x 为活跃维护线；模块化拆分（spring-boot-autoconfigure 按技术拆分、非 JPMS）、exclude 条目重定位（Moderne/OpenRewrite 迁移配方）、Jackson 3（tools.jackson，官方博客明确 2/3 可共存）、spring-retry 并入 spring-core 与 maxRetries 语义、@ConcurrencyLimit（官方博客 Core Spring Resilience Features）、H2 控制台默认不暴露与 Security 旧 DSL 移除（社区实测记录，以官方迁移指南为准）。一切以 docs.spring.io 与 GitHub 官方迁移指南为准。