[Java] SpringBoot官宣停止维护3.2.x-3.4.x：4.0升级指南及避坑要点

技术的迭代速度有时确实快得让人措手不及。

就在前不久，Spring Boot 4.0 正式发布。随之而来的一个关键变化是，Spring Boot 3.2.x、3.3.x 和 3.4.x 这些在2024年发布的版本，官方已经宣布停止维护，这意味着它们将不再获得免费的安全更新和错误修复。

下图来源于 Spring Boot 官方文档的支持政策页面：https://spring.io/projects/spring-boot#support 。

这个变动对许多正在运行的旧项目影响或许有限，毕竟还有很多项目停留在 2.x 甚至 1.x 版本。对于公司项目而言，如果当前版本运行稳定，通常不建议盲目升级。升级带来的收益老板未必能看到，但一旦出现问题，责任却可能落在开发者身上。

然而，对于新启动的项目或者个人学习项目，使用相对较新且处于官方支持周期的版本是更明智的选择。例如，我维护的一个 InterviewGuide 项目，最初为了图方便直接复用了旧项目的部分依赖，导致其 Spring Boot 版本停留在 3.3，这给我后续的升级工作带来了不小的麻烦。

应不少朋友的建议，我近日将这个项目升级到了 Spring Boot 4.0。整个过程踩了不少坑，尤其是 Jackson 3 的包名变更，堪称一次“史诗级”的破坏性更新。下面就将这份详细的升级指南与避坑要点分享出来，希望能为大家提供参考。

为什么要升级？

Spring Boot 4.0.0 基于 Spring Framework 7.0，全面支持 Java 25（包含虚拟线程优化）。其核心新特性包括：HTTP Service Clients 简化远程调用；原生 API 版本管理；全面采用 JSpecify 空安全体系（默认非空，编译期预防 NPE）；关键依赖升级至 Jackson 3.0、Tomcat 11、Hibernate 7.1 等；模块化设计改进；优先支持 Gradle 9；Redis 静态主从配置；移除对 Undertow 的内置支持。

关于这些新特性，我之前写过一篇详细的解读文章：《Spring Boot 4.0 正式发布，人已麻。。。》。

版本变更总览

首先需要明确一点：升级时切勿“跳级”。官方推荐的升级路径是 3.3/3.4 → 3.5 → 4.0。遵循这条路径可以规避掉大约90%的潜在问题。

以下是本次升级涉及的核心组件版本变化：

组件	升级前	升级后
Spring Boot	3.3.6	4.0.1
Spring Framework	6.x	7.x
Spring AI	1.1.2	2.0.0-M1
Redisson	3.24.3	4.0.0
Gradle	8.8	8.14
Hibernate	6.x	7.2.0.Final
Tomcat	10.x	11.0.15
Jackson	2.x	3.x
iText	7.2.5	8.0.5
MapStruct	1.5.5.Final	1.6.3

升级步骤详解

Step 1: 升级 Gradle

Spring Boot 4.0 要求使用 Gradle 8.14 或更高版本。首先需要升级 Gradle Wrapper：

# 临时使用旧版本 Spring Boot 执行 wrapper 升级命令
./gradlew wrapper --gradle-version=8.14

然后，修改 gradle/wrapper/gradle-wrapper.properties 文件中的分发地址：

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip

Step 2: 更新依赖版本

如果你使用了 Gradle 的版本目录（Version Catalog）功能，通常在 gradle/libs.versions.toml 文件中集中管理依赖版本。需要更新其中的版本号：

[versions]
spring-boot = "4.0.1"
spring-ai = "2.0.0-M1"
redisson = "4.0.0"
mapstruct = "1.6.3"
aws-sdk = "2.29.51"
itext = "8.0.5"
lombok = "1.18.36"
junit-jupiter = "5.12.0"

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.7" }

libs.versions.toml 是 Gradle 7.4 版本开始正式推荐的 “版本目录” 文件，它的核心作用是 集中管理项目中所有的依赖库及其版本号。

Step 3: 模块化重构 (Starter 变更)

Spring Boot 4.0 采用了更细粒度的模块化设计，一些 starter 的命名发生了变化，最典型的是 Web 模块：

// 升级前
implementation 'org.springframework.boot:spring-boot-starter-web'

// 升级后
implementation 'org.springframework.boot:spring-boot-starter-webmvc'

一个完整的 build.gradle 依赖变更示例如下：

dependencies {
    // Spring Boot Starters (Boot 4.0 modular design)
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    // Spring AI 2.0
    implementation "org.springframework.ai:spring-ai-starter-model-openai:${libs.versions.spring.ai.get()}"
    implementation "org.springframework.ai:spring-ai-starter-vector-store-pgvector:${libs.versions.spring.ai.get()}"

    // Redisson 4.0
    implementation "org.redisson:redisson-spring-boot-starter:${libs.versions.redisson.get()}"

    // iText 8
    implementation "com.itextpdf:itext-core:${libs.versions.itext.get()}"
    implementation "com.itextpdf:font-asian:${libs.versions.itext.get()}"
}

Step 4: 史上最坑的 Jackson 3 迁移

这是本次升级最棘手的部分。Jackson 3 将包名从 com.fasterxml.jackson 全面改为了 tools.jackson。这意味着项目中所有相关的导入语句都会失效。

需要修改的导入语句对照表：

升级前	升级后
com.fasterxml.jackson.databind.ObjectMapper	tools.jackson.databind.ObjectMapper
com.fasterxml.jackson.core.type.TypeReference	tools.jackson.core.type.TypeReference
com.fasterxml.jackson.core.JsonProcessingException	tools.jackson.core.JacksonException

示例代码修改：

// 升级前
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;

try {
    String json = objectMapper.writeValueAsString(data);
} catch (JsonProcessingException e) {
    // 处理异常
}

// 升级后
import tools.jackson.core.JacksonException;
import tools.jackson.core.type.TypeReference;
import tools.jackson.databind.ObjectMapper;

try {
    String json = objectMapper.writeValueAsString(data);
} catch (JacksonException e) {
    // 处理异常
}

通常需要在 PdfExportService、RedisService 等核心业务类中，利用 IDE 的全局搜索和替换功能，将所有 com.fasterxml.jackson 替换为 tools.jackson。

Step 5: Redisson 4.0 API 迁移

Redisson 4.0 对部分类进行了包结构的重组，例如 StreamMessageId 等 Stream 相关类被移到了新的包下：

// 升级前
import org.redisson.api.StreamMessageId;

// 升级后
import org.redisson.api.stream.StreamMessageId;

这个变更涉及的文件相对较少，可能包括：

• infrastructure/redis/RedisService.java
• modules/resume/listener/AnalyzeStreamConsumer.java
• modules/knowledgebase/listener/VectorizeStreamConsumer.java

验证升级结果

完成上述步骤后，运行以下命令来验证升级是否成功：

# 编译项目
./gradlew :app:compileJava

# 运行测试
./gradlew :app:build

# 启动应用
./gradlew :app:bootRun

如果升级成功，应用启动日志应该会显示类似以下信息：

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v4.0.1)

... Tomcat initialized with port 8080 (http)
... Starting Servlet engine: [Apache Tomcat/11.0.15]
... Redisson 4.0.0
... HHH000001: Hibernate ORM core version 7.2.0.Final

参考资料

• Spring Boot 4.0 发布公告[1]
• Spring Boot 4.0 Migration Guide[2]
• Spring AI 2.0.0-M1 发布公告[3]
• Redisson Changelog[4]
• Jackson 3 Release Notes[5]

总结

本次 Spring Boot 4.0 的升级主要涉及以下几个方面：

1. 构建工具升级：要求 Gradle 8.14+ 版本。
2. 模块化变更：例如 starter-web 变为 starter-webmvc。
3. Jackson 3 迁移：包名从 com.fasterxml.jackson 改为 tools.jackson，这是最大的变更点。
4. 第三方库兼容：需要将 Redisson、Spring AI 等依赖升级到对应的兼容版本。

遵循官方的推荐升级路径，可以更平滑地完成迁移。升级过程中遇到的大多数问题都与包名变更有关，通过全局搜索替换通常可以解决。

具体到 InterviewGuide 这个项目的更新内容，可以查看这个 Commit： https://github.com/Snailclimb/interview-guide/commit/f7bb05980b725c8658f93a4c511bf4b2ec616b82 。

关于构建工具的选择，也有朋友建议将项目从 Gradle 改回国内使用更广泛的 Maven。当然，也有不少开发者认为 Gradle 的构建方式更灵活高效。我个人的考虑是，除了偏好 Gradle 的简洁外，也想和 Spring Boot 官方的构建方式保持一致。构建工具本身对项目的技术架构影响并不大，更多是 开发流程和团队协作 习惯的选择。

项目地址：

• Github：https://github.com/Snailclimb/interview-guide
• Gitee：https://gitee.com/SnailClimb/interview-guide

---

参考资料
[1] Spring Boot 4.0 发布公告: https://spring.io/blog/2025/11/20/spring-boot-4-0-0-available-now/
[2] Spring Boot 4.0 Migration Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
[3] Spring AI 2.0.0-M1 发布公告: https://spring.io/blog/2025/12/11/spring-ai-2-0-0-M1-available-now/
[4] Redisson Changelog: https://github.com/redisson/redisson/blob/master/CHANGELOG.md
[5] Jackson 3 Release Notes: https://github.com/FasterXML/jackson/wiki/Jackson-Release-3.0

如果你在升级过程中遇到了其他问题，或者对技术选型有不同见解，欢迎到 云栈社区 的 开源实战 板块与其他开发者交流讨论。