从 Spring Boot 3.5.13 升级到 4.1：先分清已完成事项与真正风险

Spring Boot 4.1 不是一次普通的依赖升级。它建立在 Spring Framework 7、Jakarta EE 11 和 Servlet 6.1 之上，周边的 Spring Cloud、Nacos Client、Web 容器、JSON、数据访问和自研 starter 也会一并跨越大版本。

但升级评估最容易犯的错误，是把已经解决的问题重新列为风险。本文记录一次实际升级前的梳理方法：起点已经是 Spring Boot 3.5.13、JDK 25、Nacos Server 3.1.2，历史定制查询扩展也已经移除。于是评估的重点不再是 Boot 3.1 或 Nacos 2 的历史兼容问题，而是 3.5 到 4.1 的真实断点。

上一篇Spring Boot 从 3.1.7 升级到 3.5.13已经给出了编译、Pod 启动、完整 Actuator 健康检查和中间件验证方法。本文只聚焦 Boot 4 新增的兼容风险，避免把同一份通用清单再写一遍。

本文讨论的是升级路线和验证边界，不代表把版本号改为 4.1 后即可直接上线。

脱敏说明：文中不包含项目名、服务名、仓库路径、域名、集群信息、命名空间、Data ID、账号或真实业务数据；配置片段均为占位示例。

先固定基线

先在变更单中写清楚当前状态，避免后续讨论混入过期信息：

项目	当前状态	本次是否需要处理
Spring Boot	3.5.13	升级到 4.1
JDK	25	保持，不需要回退
Nacos Server	3.1.2	保持，不迁库、不重建配置
历史定制查询扩展	已移除	无需移植
复杂查询	已下沉为显式 SQL	保持 Repository 边界并回归结果

Nacos Server 已升级到 3.1.2，只说明服务端、数据库和配置数据可以继续使用；它不能自动证明某个 Spring Cloud Alibaba Client 已兼容 Spring Boot 4.1。Server 与 Client 是两条独立的兼容链。

第一个硬边界：Spring Cloud Alibaba 对 4.1 的支持

Spring Cloud 官方已经说明，2025.1.2 开始支持 Spring Boot 4.1.x。因此 Boot 4.1 的 Spring Cloud 目标版本应是：

<spring-cloud.version>2025.1.2</spring-cloud.version>

但 Spring Cloud Alibaba 的官方兼容表目前写的是：

Spring Cloud Alibaba 2025.1.0.0
Spring Cloud 2025.1.0
Spring Boot 4.0.0

并且将该分支描述为适配 Spring Boot 4.0.x。4.0.x 不是 4.1.x 的泛称，不能据此宣称 2025.1.0.0 已获得 Boot 4.1 的官方支持。

这不等于该组合一定无法运行，而是要区分两种结论：

官方支持：兼容矩阵明确列出对应版本。
本地验证可用：通过依赖收敛、启动、注册、配置读取和业务回归得到的项目结论。

在 Alibaba 发布明确的 Boot 4.1 适配版本前，若要直接推进 Boot 4.1，应把下面的组合当作验证对象，而不是当作默认的生产承诺：

Spring Boot 4.1.x
Spring Cloud 2025.1.2
Spring Cloud Alibaba 2025.1.x
Nacos Server 3.1.2

官方依据：Spring Cloud 版本兼容表、Spring Cloud Alibaba 2025.x 版本说明。

Nacos 不迁数据，但应用配置加载方式要迁

Spring Cloud Alibaba 2025.x 不再支持 Spring Cloud Bootstrap。应用若仍依赖：

bootstrap.yml
spring.cloud.bootstrap.enabled

就要改为 Spring Boot Config Data 方式，例如：

spring:
  config:
    import:
      - optional:nacos:<data-id>?group=<group>

具体 Data ID 是否拆分，以及 Group、Namespace、用户名和地址等细节，沿用目标环境定义即可，且不应写入公开文档；变的是“应用在启动阶段如何读取配置”，不是 Nacos 中存储的数据格式。

迁移完成后，必须验证两个方向：

启动时能加载必填配置，例如 Feign URL、数据源、Redis、消息队列地址。
运行中配置刷新、服务注册、实例发现仍正常。

Boot 4 自身带来的主要变化

1. Undertow 不能再作为嵌入式容器

Boot 4 的 Servlet 6.1 基线与 Undertow 不兼容，官方已移除 Undertow starter 和嵌入式 Undertow 支持。若最终依赖树使用 Undertow，需要切换到 Tomcat 11 或 Jetty 12，并删除 server.undertow.* 配置。

不要仅凭一份公共配置就认定所有服务都需要改容器；应先确认每个服务的最终依赖树和实际启动日志。

2. Boot 模块和 starter 重新拆分

Boot 4 将许多大 jar 拆成更细的模块。自研 starter、直接依赖 Boot 内部类、手写自动配置的模块尤其容易在编译期暴露问题。

首轮可使用 spring-boot-starter-classic 和 spring-boot-starter-test-classic 获得接近 Boot 3 的完整 classpath，先恢复编译、启动和测试；稳定后再按实际功能替换为更精确的 starter。不要让同一个自研 starter 同时承诺 Boot 3 与 Boot 4 二进制兼容，应建立独立的 Boot 4 版本线。

3. Jackson 3 是方向，不应与框架升级捆绑冒险

Boot 4 默认偏向 Jackson 3，而 Jackson 3 的坐标和部分包名发生变化。对已有大量 ObjectMapper、消息序列化、日期格式化、导入导出逻辑的系统，首轮应优先保持 Jackson 2 的兼容行为：

spring:
  jackson:
    use-jackson2-defaults: true

必要时使用 Boot 提供的临时 Jackson 2 模块。待 HTTP 响应、Kafka/Rabbit 消息和导出文件全部回归通过后，再单独规划 Jackson 3 迁移。否则一旦出现异常，很难判断是 Boot、Jackson 还是业务序列化造成的。

4. 数据访问组件必须按 Boot 4 重新确认

已移除的历史定制查询扩展不再是风险，但以下组件仍需确认版本：

Hibernate 7：实体映射、方言、JPA Criteria、原生 SQL、JSON 与日期字段。
动态数据源：dynamic-datasource-spring-boot3-starter 不能直接假定兼容 Boot 4。
MyBatis-Plus：分页、拦截器、多数据源事务与 SQL 日志。
Redis、Kafka、Rabbit：客户端、序列化、监听器、重试和消息头。

每一项都应采用“升级依赖后运行测试”的方式确认，而不是只看 Maven 能否下载 jar。

5. 安全、测试和运维也会跟随升级

Boot 4 同时带来 Spring Security 7、Spring Kafka 4、Spring AMQP 4、Spring Batch 6 等大版本升级。需要重点验证：

登录、Token、权限注解、Feign 调用身份。
消息消费、反序列化、重试和幂等。
@SpringBootTest 下的 Web 测试；需要时显式增加 @AutoConfigureMockMvc。
Actuator 健康检查。Boot 4 默认启用 liveness/readiness 分组，Kubernetes 探针、Prometheus 抓取和优雅停机都要复核。

在 3.5 验收基线上的实施顺序

建立 4.1-SNAPSHOT 分支
        ↓
确认 Cloud / Alibaba Client 精确版本
        ↓
迁 Nacos Config Data，处理父工程自研 starter
        ↓
父工程全量编译与测试
        ↓
升级一个试点服务并在本地连接 Nacos 3.1.2
        ↓
test Kubernetes 发布与业务回归
        ↓
逐服务推广

建议先选一个业务边界清晰、测试较完整的服务作为试点，而不是一次升级所有服务。父工程新版本使用独立 Maven 版本，例如 4.1-SNAPSHOT，避免覆盖仍在运行的 3.5.13-SNAPSHOT。

Boot 4 试点的增量验收清单

下面只列出相对于上一篇新增的检查项。目标 JDK 编译、Pod 启动、完整 /actuator/health、数据库和消息中间件连通性等通用验收仍然必须执行，但不在这里重复展开。

启动与基础设施

Spring Cloud 已使用支持 Boot 4.1 的 2025.1.2+，依赖树中没有旧 Release Train。
Spring Cloud Alibaba Client 的精确版本有兼容矩阵或试点验证证据，不能只用 Nacos Server 版本代替。
Nacos 配置已改为 Config Data，启动链路不再依赖 Spring Cloud Bootstrap。
实际 Web 容器是 Tomcat 11 或 Jetty 12，依赖树与配置中没有残留 Undertow。
spring-boot-starter-classic 只作为过渡；拆分 starter 和属性迁移完成后应移除。

业务与数据

Hibernate 7、MyBatis-Plus 和动态数据源分别完成分页、事务、原生 SQL 与多数据源回归。
Spring Batch 6 的 Job 注册、元数据表、重启和分区执行语义通过验证。
Spring Kafka 4、Spring AMQP 4 的消息头、序列化、重试、死信和幂等行为没有变化。
Jackson 3 与临时 Jackson 2 兼容路径只能选择一条作为生产基线，并完成 HTTP、消息和导入导出回归。

接口契约

前端核心页面请求和错误提示。
日期、金额、枚举、null 字段、分页结构。
HTTP API 与消息 JSON 的反序列化兼容。

结论

从 Spring Boot 3.5.13 升到 4.1，Nacos 3.1.2 与已移除的历史定制查询扩展不再是阻碍。真正需要优先确认的是 Spring Cloud Alibaba Client 是否对 Boot 4.1 有明确支持；随后按 Nacos 配置加载、Boot 模块化与 Web 容器、数据访问、Jackson 和自研 starter 的顺序推进。

先建立“本地和 test 环境验证可用”的证据，再将其确立为生产标准，才是这类跨大版本升级可控的做法。Boot 官方迁移指南可作为逐项排查清单：Spring Boot 4.0 Migration Guide。