springboot 项目 从jdk 8 升级到jdk21 会面临哪些问题

前言

兄弟们最近上班没时间写博客啊，今天又来水一篇！

Spring Boot 项目从 JDK 8 升级到 JDK 21（长期支持版 LTS），会面临哪些问题。 主要就是API变更、框架适配、第三方依赖、构建工具配置 问题。

推荐阅读: JDK从8升级到21的问题集（京东云）

springboot项目从1.8到21面临的问题

一、JDK API 变更导致的问题

JDK 8 到 21 有大量 API 废弃、移除或行为变更，核心影响点：

1. 已移除的 API

• sun.misc.BASE64Encoder/Decoder：JDK 8 中已标记废弃，JDK 16 + 移除，需替换为java.util.Base64；
• Thread.stop()、Thread.suspend()：JDK 11 + 严格限制，调用会抛 UnsupportedOperationException；
• com.sun.image.codec.jpeg.JPEGCodec：JDK 9 + 移除，需替换为ImageIO；
• java.security.acl包：JDK 17 + 标记为废弃，JDK 21 中部分类移除，需改用java.security.Policy。

2. 模块化限制（JPMS）

JDK 9 + 引入模块系统，默认不允许访问sun.*、com.sun.*等内部 API：

• 问题表现：运行时抛IllegalAccessError或ModuleNotFoundException；

• 解决方案：

  • 替换内部 API 为标准 API（如sun.misc.Unsafe替换为VarHandle）；
  • 若必须使用，需在启动参数中添加--add-exports（如--add-exports java.base/sun.misc=ALL-UNNAMED）。

3. 日期时间 API（可选）

JDK 8 的Date/Calendar未移除，但 JDK 1.8 引入的java.time（JSR 310）在 21 中更完善，若项目仍用旧 API，需注意：

• SimpleDateFormat的线程安全问题未解决，但 JDK 21 无变更；
• 推荐逐步替换为LocalDateTime、ZonedDateTime等。

4. 字符串与集合 API 变更

• String.trim()：JDK 11 + 行为不变，但String.strip()（去除 Unicode 空白）成为推荐替代；
• Collections.singletonMap()：JDK 9 + 新增Map.of()、List.of()等不可变集合工厂方法，旧代码兼容，但需注意不可变集合的特性（不支持修改）。

二、Maven版本兼容

JDK 21 对构建工具版本有最低要求，旧版本构建工具无法识别 JDK 21 的编译参数：

Maven ：需升级到 3.8.0+（推荐 3.8.5+），且maven-compiler-plugin需升级到 3.10.0+（否则无法编译 JDK 21 代码）。

<plugin>
    <groupId>org.apache.maven.plugins</groupId> 
    <artifactId>maven-compiler-plugin</artifactId> 
    <version>3.13.0</version> 
    <configuration> 
        <release>21</release><!-- 统一使用release参数 --> 
    </configuration> 
</plugin>

三、Spring Boot 框架本身和中间件版本

1. Spring Boot 版本必须升级

JDK 21 仅支持Spring Boot 3.1+ （官方明确：Spring Boot 3.0 支持 JDK 17，3.1 开始支持 JDK 21），若项目当前是 Spring Boot 2.x（仅支持 JDK 8-17），需先升级到 Spring Boot 3.x，这会带来连锁变更：

• Spring Boot 3.x 核心变更：

  • 基于 Spring Framework 6.x，要求 Java 17+（JDK 21 兼容）；
  • 移除对javax.*包的支持，全面迁移到jakarta.*（如jakarta.servlet替代javax.servlet，jakarta.persistence替代javax.persistence）；
  • 自动配置类、starter 依赖有调整（如spring-boot-starter-web底层依赖 Tomcat 10+，而 Tomcat 10 + 也基于 Jakarta EE 9）。

• 内嵌容器 ：Tomcat 9（JDK 8）→ Tomcat 10+（JDK 17+），Tomcat 10 + 的 Servlet API 从javax.servlet迁移到jakarta.servlet，若项目中有自定义 Servlet/Filter/Listener，需修改包名；
• 日志框架 ：Spring Boot 3.x 默认使用 Logback 1.4+，Logback 1.4 + 要求 JDK 11+，需确认日志配置文件（如logback.xml）是否适配；
• 缓存、事务等注解 ：@Transactional、@Cacheable等注解底层依赖的 API 无大变更，但需确认 Spring Framework 6.x 的行为变更（如事务传播机制、缓存管理器适配）。

2、第三方依赖兼容问题

这是升级中最常见的 "坑"，大量第三方库在 JDK 21 下无法运行：

1. 数据库驱动

• MySQL 驱动 ：mysql-connector-java 8.0.28 + 才支持 JDK 17+，需升级到 8.0.30+（适配 JDK 21）；
• Oracle 驱动：ojdbc8 仅支持 JDK 8-11，需升级到 ojdbc11（支持 JDK 11-21）；
• PostgreSQL 驱动：42.2.x 仅支持 JDK 8，需升级到 42.5+（支持 JDK 17+）。

2. 中间件客户端

• Redis ：jedis 3.7.x 仅支持 JDK 8，需升级到 4.0+（支持 JDK 11+）；
• Kafka ：kafka-clients 2.8.x 支持 JDK 8，3.0 + 支持 JDK 11+，需升级到 3.4+（适配 JDK 21）；
• Elasticsearch：7.17.x 支持 JDK 8-17，8.x 支持 JDK 17+，需升级客户端到 8.x（适配 JDK 21）。

3. 其他常用库

• MyBatis：3.5.9 + 支持 JDK 17+，需升级（旧版本 3.5.6 以下在 JDK 21 中会抛类加载异常）；
• FastJSON：1.2.83 以下存在 JDK 17 + 兼容问题，需升级到 2.0+（FastJSON2）；
• Apache Commons ：commons-lang3需升级到 3.12.0+，commons-collections4需升级到 4.4+；
• Lombok ：1.18.20 以下不支持 JDK 16+，需升级到 1.18.30+（适配 JDK 21），且需在 Maven 中配置lombok.version为最新版。

四、运行时与启动参数问题

1. JVM 参数变更

• JDK 8 的-XX:+UseConcMarkSweepGC（CMS 垃圾收集器）在 JDK 14 中废弃，JDK 21 中移除，需替换为-XX:+UseG1GC（默认）或-XX:+UseZGC（JDK 15 + 正式支持，低延迟）；
• -XX:+UseParallelGC仍可用，但推荐适配新 GC；
• JDK 11 + 移除-XX:+UseCGroupMemoryLimitForHeap，需改用-XX:+UseContainerSupport（默认开启）。

2. 模块化启动参数

若项目未适配模块化，需添加启动参数避免模块冲突：

java --add-modules ALL-MODULE-PATH \
     --add-exports java.base/sun.misc=ALL-UNNAMED \
     -jar your-app.jar

总结

主要的风险点：spring boot 需要升级到Spring Boot 3.1+ ，大版的升级就涉及到很多中间件需要跟着升级，其次就是一些API可能被移除了，这块编译就阶段就能解决。还有就是我们maven版本和编译插件需要升级。