Spring Boot 4 迁移避坑清单：Jackson 3、starter 拆分与最低 JDK 口径核对（含若依/芋道/CRMEB 升级对照）

Spring Boot 4 迁移避坑清单：Jackson 3、starter 拆分与最低 JDK 口径核对（含若依/芋道/CRMEB 升级对照）

Spring Boot 4 的迁移不是"改一行版本号"的常规升级。从现有资料看，围绕它的生态已经真实动起来：芋道（yudao）v2026.06 标注"正式发布 Spring Boot 4.X"、dromara 组织下的 RuoYi-Cloud-Plus 发布 v6.0.0、MateCloud 仓库描述写明 Spring Boot 4.0.7 与 Spring Cloud 2025 / Spring Cloud Alibaba 2025、CRMEB 多商户（Java）v3.0 预告后端升到 Spring Boot 4.1 + JDK 21 15。但与这种"集体升级"叙事同时存在的，是版本口径的明显打架：最低 JDK 有 17 与 21 两种说法，Boot 版本号有 4.0.x、4.0.7、4.1 三种表述，Spring Security 6.3.x 与 Spring Framework 7.0.1+ 的配对关系也存疑 2356。

本文面向已经在 Boot 3.x 上生产运行、且多基于若依 / 芋道 / CRMEB 二次开发的 Java 后端团队，目标是给出一份可执行的迁移手册，而不是版本特性宣传。全文按三档标注信息可信度：

• 【素材可追溯】：素材中有明确、可定位的出处陈述，但仍不等于官方确认；
• 【口径冲突】：不同素材说法互相矛盾，必须回到官方文档裁决；
• 【待核实】：素材未提供、或只有单篇转述，本文不替它背书，只给出核查路径。

需要预先说明一点：本次可用素材全部来自社区文章、仓库描述与预告稿，没有拿到 Spring 官方 System Requirements、Release Notes 或迁移指南原文；素材热度字段全部为 0，无法据此判断传播量级。因此凡涉及"最低 JDK""版本号""类名变更"的结论，本文一律给出核对动作而不是替官方下结论。

---

导读：三个"非线性"风险在哪一层

Boot 2 到 Boot 3 的阵痛集中在 javax.* → jakarta.* 包名替换，那是可以用全局替换和编译错误穷举解决的 3。Boot 4 的风险分布不一样，至少有三层是"编译能过、行为变了"：

1. 依赖层 ：starter 按技术点重新拆分（素材明确给出 spring-boot-starter-webmvc、spring-boot-starter-flyway 两个新名），从老项目复制 pom 会造成自动配置不生效或依赖缺失 4；
2. 序列化层：Boot 4 默认绑定 Jackson 3，JSON 输出的时间格式、null 处理、Long 精度、异常结构都可能静默变化，直接影响前后端契约 4；
3. 契约与安全层：Spring Framework 7 移除/废弃 API、Spring Security 与 OAuth2 配置写法调整，对自带认证中心的脚手架项目影响面最大 2。

---

一、迁移前先定基线：最低 JDK 口径到底听谁的

1.1 素材中的三种 JDK 口径

说法	出处	原文要点	本文判定
Java 17 最低，Java 21 / 25 推荐	CSDN《Spring Boot 4 震撼发布》2	环境要求表"Java 版本：最低 17，推荐 21/25"	【口径冲突】与下一行一致，可作主候选
Boot 4.x 最低 JDK = Java 17	CSDN《Spring Boot 4.0 正式发布》3	版本演进表：Boot 3.x 与 4.x 均写 Java 17	【口径冲突】与 2 一致，二者互相印证
"2026 版 Spring Boot 默认要求 Java 21+，建议 JDK 22"	CSDN《2026 版 Spring 全家桶》6	正文提示语	【待核实】可信度低，该文含 @EnableAIIntegration、@CloudNativeEnabled 等疑似自造注解
"Java 25 时代"、solon-java25 v4.0.0	CSDN《Spring Boot 4 来了》1	生态叙事，指推荐生态而非最低要求	【素材可追溯】属时代叙事，不能当版本要求
Boot 3.x 需要 Java 17+	CSDN《Spring Boot 官宣：正式弃用 Java 8》7	Boot 3.0（2022-11）要求 Java 17 及以上	【素材可追溯】是 Boot 3 的既有基线，可作迁移起点

结论：素材内 17 与 21 两说并存 ，其中 23 一致指向"最低 17"，6 的"21+"说法伴随明显可疑内容，应降权处理；"Java 25"是推荐生态而非最低门槛。最终以 Spring Boot 4.x 官方 System Requirements 页面为准，并且要分别核对 4.0 与 4.1 两条线，因为 CRMEB 的预告写的是 4.1 + JDK 21 5，MateCloud 仓库描述写的是 4.0.7 1，两者不是同一个版本线。

建议把口径固化到工程里，而不是停留在团队共识：

<properties>
    <!-- 版本号请以官方发布页/Release Notes 为准，此处仅示意占位 -->
    <java.version>17</java.version>
    <spring-boot.version>${请填写官方核实版本}</spring-boot.version>
    <maven.compiler.release>${java.version}</maven.compiler.release>
</properties>

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>${spring-boot.version}</version>
    <relativePath/>
</parent>

同时在 CI 里锁死编译目标，防止本地 JDK 高、流水线 JDK 低的隐性漂移：

java -version 2>&1 | tee jdk-baseline.txt
mvn -version
mvn -q clean verify

1.2 版本矩阵：哪些配套版本只是单篇说法

组件	素材中的表述	出处	状态
Spring Boot	4.0.x / 4.0.7 / 4.1 三种	1235	【口径冲突】需按发布页逐一核对
Spring Framework	7.0.1+	2	【待核实】单篇来源
Jakarta EE	11	2	【待核实】单篇来源
Spring Security	6.3.x	2	【口径冲突】Security 6.3 通常归 Boot 3.x 线，与 Framework 7 的配对关系存疑
Spring Cloud	2025（MateCloud 仓库描述）/ 2026.x（6）	16	【口径冲突】后者可信度低
Spring Cloud Alibaba	2025	1	【待核实】来自仓库描述转述
Hibernate	7.4	4	【待核实】单篇来源
Spring AI	2.0	6	【待核实】不进本文技术结论

这里最容易出事的是"手动指定依赖版本"。脚手架项目普遍在父 pom 里写了 spring-framework.version、spring-security.version 之类的属性覆盖，Boot 升级后这些覆盖值不会自动跟上，结果是"Boot 4 + Framework 6"这种静默错配，编译期可能不报错，运行期才炸。正确做法是：先清掉所有对 Spring 系组件的版本覆盖，交给 BOM 管理，只保留第三方组件的显式版本，再逐个确认第三方是否有 Boot 4 适配版本。

# 升级前后各导出一次依赖树，聚焦 Spring 系与序列化系
mvn -q dependency:tree -Dincludes='org.springframework*' > tree-spring-before.txt
mvn -q dependency:tree -Dincludes='com.fasterxml.jackson*,tools.jackson*' > tree-json-before.txt

1.3 "落后半步"策略的适用边界

CSDN 的一篇迁移文给出的经验是"版本永远落后半步"：等 Boot 4 出到稳定的 4.0.x 补丁版、等 Spring Cloud 发布对应正式版本，再规划迁移 3。这条建议对多数业务系统成立，但不是普适规则：

项目类型	建议	理由
生产稳定、改动窗口少的业务系统（金融、政企后台）	等补丁线稳定、Spring Cloud 配套齐全后再迁	回归成本远高于新特性收益
脚手架/基础组件维护方（若依、芋道二开团队）	提前动，但只在独立分支做	你的下游在等你，晚迁会把兼容压力转嫁给自己
需要 JDK 21/25 新特性或虚拟线程收益的项目	可提前，但先在 Boot 3.x 上把 JDK 升上去	把"JDK 升级"与"Boot 升级"解耦，是降低排错维度的关键
仍在 Java 8/11 的项目	先完成 JDK 升级，本轮不碰 Boot 4	Boot 3 就已要求 Java 17 7，先补前置课

关键动作是把两个变量拆开：先把 JDK 从 8/11 升到 17 或 21 并在 Boot 3.x 上跑稳，再动 Boot 4。混在一起升，出问题时无法判断是 JDK 语义变化（如默认 GC、反射强封装、序列化过滤器）还是框架行为变化。

---

二、依赖层：starter 拆分带来的第一轮编译失败

2.1 starter 拆分：只写素材确证的部分

素材中可确证的新命名只有两个：spring-boot-starter-webmvc、spring-boot-starter-flyway，并明确提示"Boot 4 的 starter 也按技术拆分了" 4。素材没有给出完整映射清单，本文不做推演。其余条目必须通过下面两种方式自查：

方式一：用 Spring Initializr（start.spring.io）在目标 Boot 版本下生成一个最小工程，勾选你需要的能力，直接看它产出的依赖坐标；这是最可靠的"官方口径清单"。

方式二：对老项目做依赖树快照，找出 Boot 系坐标：

mvn -q dependency:tree -Dincludes='org.springframework.boot' -DoutputFile=boot-starters.txt

把输出逐条与 Initializr 结果比对，形成自己项目的映射表：

旧坐标（Boot 3.x 实际使用）	新坐标（以 Initializr 为准）	变化类型	本项目是否受影响
待填写	spring-boot-starter-webmvc 4	拆分/更名	待核实
待填写	spring-boot-starter-flyway 4	拆分/更名	待核实
其余	待核实	待核实	待核实

2.2 为什么"从老项目复制依赖"会翻车

一个典型的排查路径（已匿名化，仅描述过程，不构成对具体项目的断言）：

1. 团队把 Boot 3 工程的 pom 整体复制，只把 parent 版本号改成 Boot 4；
2. 启动无报错，但某个自动配置（如数据源初始化、序列化配置）没生效，表现为"配置写了不生效"；
3. mvn dependency:tree 才发现旧 starter 坐标仍被引入，与新拆分坐标并存，BOM 选择了不同的传递依赖；
4. 删除旧坐标、改用 Initializr 生成的新坐标后问题消失。

根因在于：starter 不只是"一组依赖"，它还携带自动配置注册（AutoConfiguration.imports 一类的元数据）。新旧坐标并存时，可能出现"依赖在、自动配置不在"或"两套自动配置抢占"的形态，这类问题编译期完全看不见。

正确姿势：用 Initializr 生成最小可运行工程 → 让它跑起来 → 逐项把自己的模块与依赖搬过去，每搬一项跑一次冒烟。不要一次性替换整个 pom。

2.3 parent/BOM 与第三方组件对齐

第三方组件在 Boot 4 下的兼容状态，素材基本没有覆盖，本文一律标【待核实】，不写版本号：

组件	常见用途	Boot 4 适配状态	核查方式
MyBatis-Plus	ORM 增强	待核实	官方 Release Notes / issue 中检索 Boot 4 关键词
Redisson / Lettuce	分布式锁、缓存客户端	待核实	官方 release 页 + 依赖树中的传递依赖冲突
SpringDoc / Knife4j	OpenAPI 文档	待核实	官方兼容矩阵；文档类组件对 Spring MVC 版本敏感
EasyExcel / Excel 类库	导入导出	待核实	依赖树中是否传递引入旧版 Jackson
EasyQuery	查询扩展（zadmin 采用）1	待核实	该项目以 Boot 4 + easy-query 为卖点，可作参考样本
Quartz / XXL-JOB	定时任务	待核实	任务调度器对线程模型变化敏感，需单独压测

核查动作统一为三步：看官方 release 是否声明支持；看 issue 区是否有 Boot 4 迁移反馈；看依赖树是否传递拉入旧版 Jackson 或旧版 Spring 模块。只要第三条命中，先处理依赖冲突，再谈功能验证。

---

三、序列化层：Jackson 3 的静默行为变化最危险

3.1 Boot 4 默认绑定 Jackson 3 意味着什么

素材明确给出的事实只有一句：Boot 4 默认是 Jackson 3 4。至于包名、模块坐标、自动配置类名的具体变化，素材没有给出可核验清单，本文不填未经核实的类名，避免把猜测写成事实。请按以下顺序核实：

1. 阅读 Jackson 官方 3.x 迁移指南，列出你实际用到的模块（core、databind、datatype-jsr310、注解模块等）；
2. 阅读 Boot 4 文档中"JSON 序列化"章节，确认自动配置绑定的类型与配置前缀是否变化；
3. 在一个最小工程里做一次序列化/反序列化往返实验，用你自己的 DTO 验证，而不是相信文档示例。

"是否可以留在 Jackson 2"这个问题，同样需要官方文档裁决。工程上的稳妥假设是：不要指望 2 与 3 长期并存于同一条依赖链。如果你的项目依赖了大量 Jackson 2 专属注解模块或第三方库硬绑 Jackson 2 API，那么应把"第三方库的 Jackson 版本兼容性"列为本轮迁移的头号阻塞项，先解决它再升 Boot。是否允许并存、并存的代价是什么，属【待核实】，请以官方文档为准。

3.2 回归测试清单：五类最容易被静默改写的契约

序列化行为变化的特点是：不报错、不告警，只有前端在某一天发现字段没了、时间串变了、Long 精度丢了。因此回归必须以契约快照形式固化。建议做法是通过 HTTP 层断言响应 JSON 原文，而不绑定任何 Jackson 类名，这样测试代码在 2 与 3 之间都能跑：

@SpringBootTest
@AutoConfigureMockMvc
class JsonContractRegressionTest {

    @Autowired
    private MockMvc mockMvc;

    // 1) 时间格式：断言输出形态，而不是断言某个 Formatter 类
    @Test
    void dateTimeFormatShouldNotChange() throws Exception {
        mockMvc.perform(get("/api/demo/order/1"))
               .andExpect(status().isOk())
               .andExpect(jsonPath("$.createTime").value("2026-09-30 10:00:00"));
    }

    // 2) null 字段策略：默认是否序列化为 null，还是直接省略
    @Test
    void nullFieldPolicyShouldNotChange() throws Exception {
        String body = mockMvc.perform(get("/api/demo/order/2"))
                             .andReturn().getResponse().getContentAsString();
        // 按你当前线上契约二选一：包含 "remark":null 或不含 remark
        assertThat(body).contains("\"remark\":null");
    }

    // 3) Long 精度：ID 类字段是否被输出为字符串，避免 JS Number 溢出
    @Test
    void bigIdShouldKeepPrecision() throws Exception {
        mockMvc.perform(get("/api/demo/order/3"))
               .andExpect(jsonPath("$.id").value("9007199254740993"));
    }

    // 4) 空集合与空字符串
    @Test
    void emptyCollectionPolicyShouldNotChange() throws Exception {
        mockMvc.perform(get("/api/demo/order/4"))
               .andExpect(jsonPath("$.items").isArray())
               .andExpect(jsonPath("$.items", hasSize(0)));
    }

    // 5) 异常响应体结构
    @Test
    void errorBodyShapeShouldNotChange() throws Exception {
        mockMvc.perform(get("/api/demo/order/not-a-number"))
               .andExpect(status().isBadRequest())
               .andExpect(jsonPath("$.code").value(400))
               .andExpect(jsonPath("$.msg").isNotEmpty());
    }
}

落地时再补三件事：

• 黄金文件比对 ：把线上真实响应（脱敏）存为 src/test/resources/golden/*.json，迁移前后逐字段 diff；
• 前端契约校验：若前端已用 OpenAPI 生成 TS 类型 4，升级后重新生成并让前端编译一遍，编译失败即契约破坏；
• 全量 DTO 扫描：对所有对外 DTO 的时间、ID、可空字段建清单，逐项确认输出形态，而不是只测几个接口。

特别提醒 Long 精度问题：JS 的 Number 安全整数上限是 2^53-1，雪花 ID 类字段一旦从字符串变回数字，前端会在高位静默丢精度。这类问题在单元测试里几乎测不出来，必须用真实的长 ID 值在 HTTP 响应层验证。

3.3 JSONB / Hibernate 场景

素材提到：Boot 4 默认 Jackson 3，Hibernate 7.4 自带 Jackson3JsonFormatMapper，@JdbcTypeCode(SqlTypes.JSON) 可直接用 4。这是单篇来源，且"7.4"这个版本号与该 Mapper 的归属需以 Hibernate ORM 官方文档核对，本文标【待核实】。

适用范围也要收窄：该结论最可能成立的是"实体里有 JSON/JSONB 字段映射"的组合，常见于 PostgreSQL 的 JSONB 列。使用 MySQL JSON 列或其他数据库时，类型映射与方言行为并不等价，必须单独补测。示例（仅示意用法，具体注解以你使用的 Hibernate 版本文档为准）：

@Entity
public class ProductSpec {

    @JdbcTypeCode(SqlTypes.JSON)
    @Column(name = "spec_json", columnDefinition = "jsonb")
    private Map<String, Object> spec;   // 映射行为需在目标数据库上实测
}

回归要点：读写往返是否丢字段、嵌套结构是否展开、空对象写入是 {} 还是 null、既有存量数据能否被新版本正常反序列化。存量数据兼容性是 JSON 字段映射最容易被忽略的回滚障碍------一旦新版本写出旧版本读不懂的格式，回滚就不只是改版本号。

---

四、API 与安全层：废弃清理与 Security 配置迁移

4.1 被移除/废弃 API 的排查方法

不要靠"编译报错逐个撞"。推荐流程：

1. 打开编译期弃用告警，先拿到全量清单：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <compilerArgs>
            <arg>-Xlint:deprecation</arg>
            <arg>-Xlint:removal</arg>
        </compilerArgs>
        <showDeprecation>true</showDeprecation>
    </configuration>
</plugin>

2. 用静态扫描或 OpenRewrite 一类工具做批量识别（属建议，具体规则集需自行验证）；
3. 与 Spring Framework 7 官方迁移/弃用清单逐条比对，区分"早年已弃用"与"本次移除"。

这里必须纠正素材中的一处归因：有文章把 WebMvcConfigurerAdapter 列为 Boot 4 移除的典型例子 2，但该类至少在 Spring Framework 5.0 就已标记弃用，属于跨大版本累积的旧账，不是 Boot 4 新引入的问题。正确写法是直接实现 WebMvcConfigurer 接口，Spring 5 起该接口已提供默认方法，无需再继承适配器：

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/api/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST", "PUT", "DELETE");
    }
}

另外，脚手架二开项目里常见的历史包袱还包括：手写的消息转换器（HttpMessageConverter）、手写的类型转换器、直接依赖 Spring 内部包（org.springframework.boot.* 内部实现类）、反射调用私有方法。这些在 Framework 7 上的兼容性需逐项核查，尤其直接依赖内部包的部分，建议列入"必须清理"而非"暂时容忍"。

4.2 Spring Security / OAuth2 客户端配置

素材给出的"Spring Security 6.3.x"配对 Framework 7.0.1+ 的说法存疑 2，本文不据此写配置代码。对若依 / 芋道这类自带认证中心（OAuth2 授权码、JWT 令牌、多租户）的项目，影响面主要在：

• SecurityFilterChain 的构建方式与默认安全策略；
• OAuth2 Client / Resource Server 的配置项命名与绑定；
• 密码编码器、会话管理、CORS/CSRF 默认值；
• 与 Spring Cloud Gateway、Nacos 一并升级时的认证链路回归。

在没有拿到官方变更清单之前，不建议照抄网上的"Boot 4 Security 配置前后对比"代码 。可执行的动作是：把你现在的 SecurityFilterChain、OAuth2 客户端配置、JWT 解析逻辑整理成清单，逐一在官方文档中确认是否变化，然后用接口级测试验证"未登录→401、登录→200、越权→403、令牌过期→401"四条基线行为不变。

---

五、脚手架对照：若依 / 芋道 / CRMEB / RuoYi-Cloud-Plus 各自到哪一步

5.1 升级状态对照表

项目	素材中的版本口径	JDK	信源类型	状态
芋道 yudao	v2026.06，"正式发布 Spring Boot 4.X" 1	标注 jdk17/21 1	社区文章转述仓库说明	【待核实】需查官方仓库 release/README
RuoYi-Cloud-Plus（dromara）	v6.0.0 大版本 1	未提供	社区文章转述	【待核实】需查 dromara 仓库 release
CRMEB 多商户（Java）	v3.0，Spring Boot 4.1 5	JDK 21 5	官方更新预告	【预告】不能写成已落地
MateCloud	仓库描述标注 Boot 4.0.7 + Cloud 2025 + Alibaba 2025 1	未提供	仓库描述转述	【待核实】以仓库 pom/release 为准
zadmin	Boot 4 + easy-query 1	未提供	仓库卖点描述	【素材可追溯】可作参考样本
Solon（非 Spring 路线）	solon-java25 v4.0.0 1	Java 25	仓库/版本线描述	【素材可追溯】非本文主线
continew-admin	Spring Boot 3（Java 17）10	Java 17	Gitee fork 仓库描述	【素材可追溯】尚未见 Boot 4 口径
youlai-boot / youlai-mall	Spring Boot 3、Spring Cloud & Alibaba 2022 11	Java 17	Gitee fork 仓库描述	【素材可追溯】尚未见 Boot 4 口径
若依主线 RuoYi-Vue / RuoYi-Cloud	SpringBoot 系（具体版本未标注）12	未提供	Gitee 收藏集描述	【待核实】

三点必须强调：

1. CRMEB v3.0 是更新预告，文章明确是"更新预告"，且给出的是演示站信息 5，不能在内部汇报里写成"已发布"；
2. MateCloud 的 4.0.7 来自仓库描述转述 1，仓库描述与实际 pom、release 可能不同步；
3. 芋道标注 jdk17/21 与"最低 JDK 17"并不矛盾，前者是支持范围，后者是下限，但在对外沟通时应并列呈现，避免被读成"要求 21"。

5.2 二次开发项目的迁移顺序选择

维度	跟随脚手架官方升级	自行升级
前置条件	官方已发布 Boot 4 版本线，且与你当前分叉差距可控	无官方版本也可启动
合并成本	需要反复 rebase，脚手架 core 改动大时冲突严重	一次到位，但后续再合官方改动更痛
回归范围	官方升级 + 自研代码，通常更大	仅自研代码，但要自证兼容
适合场景	对 core 侵入浅、跟随更新快	对 core 侵入深、已深度定制序列化/认证
主要风险	官方升级节奏不受你控制	长期偏离主线，安全补丁跟进困难

判断标准可以量化成三个问题：你改动了脚手架 core 多少行？你是否自定义了 HttpMessageConverter / Security 过滤链 / 认证中心？你的发布窗口能不能容纳一次全量回归？三个问题里有两个为"是"，就倾向自行升级并长期维护分叉；否则等官方版本更划算。

5.3 各脚手架已知坑的社区汇总

现有素材不足以支撑这一节的逐条 issue 清单，本文不虚构任何 issue 标题或链接。请按项目在 Gitee / GitHub 的 issue 区检索关键词（Boot 4、Spring Boot 4、Jackson 3、starter、JDK 21），记录标题、链接与状态。检索不到时，应如实写"暂未发现公开 issue 记录"，而不是用推测填补。

---

六、落地执行：分阶段迁移、灰度与回滚

6.1 三阶段迁移路线

阶段	入口条件	主要动作	出口条件
一、依赖升级	JDK 已在 Boot 3.x 上跑稳	清理版本覆盖、替换 starter、处理依赖冲突	编译通过、启动通过、冒烟通过
二、行为验证	阶段一完成	JSON 契约回归、异常结构回归、任务/消息链路验证	黄金文件 diff 为零或差异已逐条确认
三、契约与安全验证	阶段二完成	鉴权四基线、文件上传下载、灰度发布	灰度无异常，回滚预案演练通过

可直接复制进 issue 模板的清单：

[ ] JDK 版本与 CI 编译目标一致，已在 Boot 3.x 验证
[ ] 清除所有对 Spring 系组件的版本覆盖
[ ] starter 旧坐标已全部替换，依赖树无重复/降级
[ ] 第三方组件兼容性逐项核查（含传递依赖中的 Jackson）
[ ] JSON 契约黄金文件 diff 已复核（时间/null/Long/空值/异常体）
[ ] 鉴权四基线测试通过（401/200/403/401）
[ ] 定时任务、消息收发、文件上传下载回归通过
[ ] 回滚制品与配置已准备，回滚演练完成

6.2 验收与回归范围界定

模块	风险等级	测试方式	说明
对外 JSON 接口	高	黄金文件 diff + 契约测试	静默变化重灾区
鉴权/授权	高	接口级四基线 + 越权用例	Security 配置变更敏感
文件上传/下载	中高	二进制往返校验	消息转换器、multipart 配置易受影响
定时任务	中	单次执行 + 并发/超时用例	线程模型变化需关注
消息收发	中高	生产-消费端到端 + 异常重试	序列化格式变了会导致旧消息不可读
报表/导出	中	抽样比对	依赖第三方序列化库
日志与监控	中	关键字段是否保留	结构化日志字段可能受序列化影响

6.3 回滚预案

触发回滚的信号建议写死为客观指标：核心接口错误率较基线上升超过约定阈值、鉴权失败率异常、契约 diff 出现未确认字段变化、消息消费出现反序列化失败。阈值由团队按自身基线设定，本文不给统一数字。

回滚边界有两条硬约束：

1. JDK 边界：如果本轮同时升了 JDK，回滚 Boot 时 JDK 是否一起回退取决于你在 Boot 3.x 上是否已验证过新 JDK。若已验证，只回退 Boot；若未验证，必须整包回退；
2. 数据边界 ：数据库 schema、JSON 字段格式、消息体格式一旦被新版本改写，回滚就不再只是制品回退。因此本轮迁移禁止顺带做数据格式迁移，两者必须分开发版。

提前准备的制品与配置：Boot 3.x 的完整可运行制品镜像、旧版配置文件、依赖锁文件、数据库迁移脚本的回滚脚本、消息体版本号（建议在消息头加 schema 版本，便于新旧共存期识别）。

---

七、避坑速查清单

7.1 迁移 Checklist

分组	检查项	状态
基线	最低/推荐 JDK 口径已按官方 System Requirements 核实，区分 4.0 与 4.1 线	待办
基线	Boot、Framework、Security、Cloud、Alibaba 版本矩阵已由官方依赖矩阵确认	待办
基线	所有 Spring 系组件的版本覆盖已清除，交由 BOM 管理	待办
依赖	starter 旧坐标已替换，映射表以 Initializr 生成结果为准	待办
依赖	dependency:tree 前后对比完成，无重复、降级、旧 Jackson 传递依赖	待办
依赖	第三方组件兼容性逐项核查并留档	待办
序列化	Jackson 3 迁移要点已按官方迁移指南逐条核对	待办
序列化	时间格式 / null 策略 / Long 精度 / 空值 / 异常体五类契约已回归	待办
序列化	存量 JSON 数据可被新版本正常反序列化	待办
序列化	JSON/JSONB 字段映射在目标数据库上实测通过	待办
API	弃用/移除 API 已系统排查（编译告警 + 静态扫描 + 官方清单）	待办
API	不再使用 WebMvcConfigurerAdapter 等历史适配器类	待办
安全	Security/OAuth2 变更已按官方文档核对，鉴权四基线通过	待办
部署	CI 编译目标与运行 JDK 一致	待办
部署	回滚制品、配置、schema 回滚脚本已准备并演练	待办

7.2 口径冲突与待核实事项

事项	现状	建议核对渠道
Boot 4 最低 JDK 17 还是 21	素材两说并存 23 对 6	Spring Boot 4.x 官方 System Requirements
Boot 4 已发布版本号（4.0.x / 4.0.7 / 4.1）	三种表述 135	Spring 官方项目页与 Release Notes
Framework 7.0.1+ 与 Security 6.3.x 的配对	单篇来源且配对存疑 2	官方依赖矩阵 / BOM
starter 拆分完整清单	仅 2 个示例 4	Initializr 生成结果 / 官方依赖文档
Jackson 3 包名、模块、自动配置类变化	素材无细节	Jackson 3 官方迁移指南 + Boot 4 文档
Hibernate 7.4 与 Jackson3JsonFormatMapper 归属	单篇来源 4	Hibernate ORM 官方文档
WebMvcConfigurerAdapter 是否属 Boot 4 移除	素材归因可疑 2	Spring Framework 迁移指南
芋道 v2026.06 实际 Boot/JDK 基线	单篇转述 1	yudao 官方仓库 release / README
RuoYi-Cloud-Plus v6.0.0 版本口径	单篇转述 1	dromara 官方仓库 release
CRMEB 多商户 Java v3.0 状态	明确为预告 5	CRMEB 官方公告 / 演示站版本信息
各脚手架 Boot 4 迁移 issue	素材缺失	Gitee / GitHub issue 检索

7.3 一句话结论

现在就迁 ：脚手架维护方、已有稳定 JDK 基线、且能承担一轮契约全量回归的项目；再等等 ：核心业务系统、Spring Cloud 配套尚未确认、或团队仍在 Java 8/11 的项目。无论哪种，先做一件事------把 JDK 口径、Boot 版本线、Spring Cloud 配套三者的官方出处写进迁移文档，这一步的成本是十分钟，收益是避免整轮迁移建立在互相矛盾的二手信息上。

---

参考资料

1 Spring Boot 4 来了:若依/芋道/RuoYi-Cloud-Plus 集体升级,Java 25 时代的迁移踩坑指南，CSDN，https://blog.csdn.net/m0_74899094/article/details/166643918

2 Spring Boot 4 震撼发布!三大王炸特性重构Java开发，CSDN，https://blog.csdn.net/spb229443329/article/details/156107503

3 Spring Boot 4.0 正式发布:虚拟线程、GraalVM 与迁移避坑指南，CSDN，https://blog.csdn.net/weixin_30086969/article/details/165651977

4 2026 年的 Spring Boot 长什么样:JDK 21 虚拟线程 + 模块化单体重建业务后端，掘金，https://juejin.cn/post/7690869043603554350

5 前后端技术栈全面换代!CRMEB 多商户(Java)v3.0更新预告，CSDN，https://blog.csdn.net/weixin_44703272/article/details/166846799

6 2026版Spring全家桶:微服务、云原生与AI集成深度解析，CSDN，https://blog.csdn.net/weixin_31986143/article/details/165060193

7 Spring Boot 官宣:正式弃用 Java 8,一文讲透升级迁移全流程，CSDN，https://blog.csdn.net/qq_41581588/article/details/166602197

8 Java 2026:从JDK 24到企业级AI Agent实战------后端开发者的技术跃迁指南，CSDN，https://blog.csdn.net/qq_42055933/article/details/161519799

9 SpringBoot3 + Nacos + Sentinel 微服务完整实战(Java17/21 适配)，掘金，https://juejin.cn/post/7655245911812620334

10 taoyeeGit 仓库列表（continew-admin / RuoYi-Cloud / seata 等 fork），Gitee，https://gitee.com/taoyeegit/projects

11 zhangwenli 仓库列表（youlai-mall / youlai-boot / RuoYi 系列），Gitee，https://gitee.com/zwlgitee/projects

12 开源框架(前后端) - XY 的星选集，Gitee，https://gitee.com/qq593413854/collections/270843