Spring Boot 项目从 JDK 8 升级到 JDK 21 会面临哪些问题

从 JDK 8 直接跨越到 JDK 21，中间隔了 9、10、11、12……直到 21 共十几个版本。这不仅是语言特性的叠加，更是运行时约束、API 生命周期和模块化规则的整体跃迁。对于长期运行在 JDK 8 上的 Spring Boot 项目而言，升级过程中遇到的问题往往不是”编译不过”这么简单，而是编译通过、启动失败，或者启动正常、运行到某个分支才抛错。本文按照问题类型逐层展开，帮助读者建立完整的排查视角。

一、JDK 内部 API 的移除与强封装

这是 JDK 8 升级到高版本时最常见、也最容易被低估的一类问题。JDK 8 时代，大量项目直接引用了 sun.*、com.sun.* 等内部实现类，编译器不会报错，运行时也能正常工作。但从 JDK 9 开始，模块系统对这些包实施了越来越严格的访问限制。

1.1 已被移除的典型 API

• Base64 编解码：早期常用的 sun.misc.BASE64Encoder / BASE64Decoder 在 JDK 8 已标记废弃，JDK 16 起正式移除。应统一替换为 java.util.Base64，它提供 getEncoder()、getUrlEncoder()、getMimeEncoder() 等多种变体，功能和性能都更优。
• 线程控制方法：Thread.stop()、Thread.suspend()、Thread.resume() 在 JDK 11 起被严格限制，调用会直接抛出 UnsupportedOperationException。正确做法是通过中断标志（interrupt() + isInterrupted()）或 volatile 状态位实现协作式停止。
• 图像编解码：com.sun.image.codec.jpeg.JPEGCodec 在 JDK 9 就被移除，应改用 javax.imageio.ImageIO 完成读写。
• 安全相关包：java.security.acl 在 JDK 17 被标记废弃，JDK 21 中部分类已移除，需迁移到 java.security.Policy 及相关接口。

1.2 模块化带来的访问限制

JDK 9 引入的 JPMS（Java Platform Module System）默认不允许未命名模块访问 sun.*、com.sun.* 等内部包。典型表现是运行期抛出 IllegalAccessError 或 ModuleNotFoundException，而编译期可能毫无提示。

处理策略分两步：

1. 优先替换：将内部 API 替换为标准 API。例如用 VarHandle 替代 sun.misc.Unsafe 的多数场景，用 java.lang.invoke.MethodHandles 替代反射绕过访问控制的做法。
2. 兜底开放：若短期内无法替换，可在启动参数中显式开放，例如：

--add-exports java.base/sun.misc=ALL-UNNAMED
--add-opens java.base/java.lang=ALL-UNNAMED

需要注意，--add-opens 用于开放反射访问，--add-exports 用于开放编译期和运行期的包导出，两者语义不同，不能混用。同时这些参数会在未来版本中逐步失效，只能作为过渡手段。

二、第三方依赖与框架版本的兼容性

Spring Boot 项目通常依赖大量 starter 和工具库，JDK 升级会连带触发依赖链的兼容问题。

2.1 字节码增强类库

字节码操作库对 JDK 版本极其敏感。老版本的字节码库可能无法识别 JDK 21 的 class 文件版本（65），导致启动时抛出 UnsupportedClassVersionError 或解析异常。常见于 ORM 框架、Mock 框架、动态代理组件中。解决方式是升级到明确声明支持 JDK 21 的版本。

2.2 Spring Boot 自身版本

Spring Boot 2.x 系列对 JDK 17 以上的支持有限，JDK 21 需要 Spring Boot 3.2 及以上版本配合 Spring Framework 6.x。这意味着升级 JDK 往往同时意味着升级 Spring Boot 大版本，而后者又要求 jakarta.* 命名空间替换 javax.*，波及 Servlet、Validation、Persistence 等大量 API。这是一次连锁升级，需要一并规划。

2.3 构建工具与插件

Maven 和 Gradle 的版本、编译插件、打包插件的版本都需要同步提升。编译参数中的 source / target 建议改为 release，以避免依赖 JDK 21 的类库却编译出低版本字节码导致的链接错误。

三、语言与标准库层面的行为变化

3.1 字符串与集合 API

• String.trim() 行为未变，但它只去除 ASCII 空白。String.strip() 在 JDK 11 引入，能识别 Unicode 空白，是更推荐的替代。
• 集合工厂方法 List.of()、Map.of()、Set.of() 在 JDK 9 引入，创建的是不可变集合，任何修改操作都会抛 UnsupportedOperationException。将旧代码的 Collections.singletonMap() 等替换过去时，必须确认后续没有写入操作。

3.2 日期时间 API

Date 和 Calendar 并未被移除，但 java.time（JSR 310）在 JDK 21 中已非常成熟。SimpleDateFormat 的线程安全问题依旧存在，且不会因 JDK 升级而改善。建议在新代码中统一使用 LocalDateTime、ZonedDateTime、DateTimeFormatter，逐步替换旧 API。

3.3 其他容易忽略的变更

• 默认字符集在 JDK 18 起统一为 UTF-8，若旧代码依赖平台默认字符集进行文件或网络读写，可能出现乱码。
• finalize() 方法在 JDK 18 起被标记废弃，依赖它做资源清理的逻辑需要改为 try-with-resources 或 Cleaner。
• 部分 GC 组合和启动参数被移除或重命名，如 -XX:+UseParallelGC 仍可用，但一些老参数会直接导致 JVM 启动失败。

四、运行时与部署层面的影响

4.1 内存与 GC

JDK 21 默认使用 G1，并提供了 ZGC、Shenandoah 等低延迟收集器。升级后需要重新评估堆大小、GC 参数和监控指标，不能直接沿用 JDK 8 的调优配置。

4.2 容器化部署

在容器环境中，JDK 21 对 cgroup 的支持更完善，但需要注意基础镜像的更新。同时，-XX:MaxRAMPercentage 等参数的行为在新版本中更符合容器内存限制，建议重新校准。

4.3 反射与序列化

JDK 21 对反射的访问控制更严格，某些依赖深度反射的序列化框架可能需要在启动参数中开放特定包。此外，JDK 21 中的虚拟线程（Virtual Threads）虽然强大，但与旧版线程池、同步块混合使用时需要谨慎评估。

五、推荐的升级路径

1. 先评估再动手：用 JDK 21 编译项目，收集所有编译警告和错误，形成问题清单。
2. 分阶段替换：优先处理内部 API 和已移除 API，再处理依赖升级。
3. 同步升级框架：Spring Boot 3.2+、Spring Framework 6.x，并完成 javax 到 jakarta 的迁移。
4. 补充启动参数：对暂时无法替换的内部 API，用 --add-opens / --add-exports 过渡。
5. 充分回归测试：重点覆盖反射、序列化、日期时间、字符集、并发等易受影响模块。
6. 灰度发布：在预发环境长时间运行，观察 GC、内存和异常日志后再全量切换。

结语

JDK 8 到 JDK 21 的升级，本质是一次涉及语言、运行时、依赖生态和部署方式的全链路改造。它带来的收益是显著的：更好的性能、更强的安全模型、更现代的并发能力。但代价是需要系统性地排查内部 API、依赖版本和框架兼容性。把上述问题按优先级逐项拆解，升级过程就能从”不可控的冒险”变成”可管理的工程任务”。