S04-A01 · Java 版本演进与团队基线

适用读者：要决定"升不升 Java 版本"的人。
前置：S04-J03（字节码与类文件版本）。
版本基线：8 / 11 / 17 / 21（LTS）。
覆盖旧文：A-1716(72) A-2336(480) = 552 点。
覆盖扩展：E-S04-019（升级收益与风险清单）。
上一篇：S04-J06 · IO 与 NIO：四种 IO 模型、Buffer/Channel 与网络编程
下一篇：S04-A02 · Excel 方案选型。

1. 一句话结论

升级 Java 版本的收益是"语言表达力 + 运行时性能"；代价是"依赖兼容 + 构建链路 + 运维基线"。 判据不是"新版好不好"，是**"你的依赖树能不能整体抬到目标版本"**。

2. 版本能力对照

版本	关键能力	迁移价值
8	Lambda、Stream、`Optional`、新时间 API	基线（存量项目）
11	`var`、标准 `HttpClient`、单文件运行	中等（构建链友好）
17	`sealed`、`record`（正式）、强封装 JDK 内部、模式匹配（预览）	高（推荐长期基线）
21	虚拟线程、`switch` 模式匹配、分代 ZGC、Sequenced Collections	高（新项目首选）

虚拟线程（21）的实际意义：把"每请求一线程"的阻塞式代码也能撑高并发——降低改造为响应式的成本（对比 S02-B02 的线程模型）。

3. 升级检查单（E-S04-019）

#	检查项	风险
1	依赖兼容：框架/中间件客户端是否支持目标版本	高（`UnsupportedClassVersionError`、反射失败）
2	强封装：JDK 内部 API（`sun.misc.*`）是否被使用	高（17 起默认拒绝，需 `--add-opens`）
3	构建工具：Maven/Gradle 与编译器插件版本	中
4	字节码工具：字节码增强/Agent（如某些监控）	中
5	容器镜像：基础镜像与 JVM 参数（GC 变化）	中
6	测试覆盖：反射/序列化/日期时区相关用例	中
7	运行时监控：APM 是否支持新版本	低-中

第 2 条最常被低估：不少老库用 sun.misc.Unsafe 或反射 JDK 内部类，17 起默认报 InaccessibleObjectException（J02 的 HashMap.table 反射就踩了这个，需要 --add-opens）。

4. 三档升级路径

路径	做法	适合
保守	留在 8/11，只做安全补丁	存量系统、依赖树老化
渐进	逐服务升级到 17，`--add-opens` 兜底反射	多数团队（推荐）
激进	直接 21 + 虚拟线程改造	新服务、IO 密集

判据："有没有一个服务能先升、出问题能回滚？" 有 → 渐进；没有 → 先做评估环境。

5. 迁移与回滚

阶段	动作	回滚
评估	依赖扫描 + 反射/Unsafe 使用清单	—
试点	1 个低风险服务升 17	镜像回退（保留旧镜像 3 个月）
推广	按服务批次，每批灰度	服务级回滚
收口	构建链统一（`maven.compiler.release`）	—

铁律：升级必须是"服务级可回滚"——不要一次性全量切换（与 S02-A02 §6 同源）。

6. 交付物

交付物	内容
版本矩阵	服务 × 当前版本 × 目标版本 × 依赖兼容状态
风险清单	强封装/Unsafe/反射/Agent 使用点
回滚方案	镜像保留期、切换开关位置
ADR	选 17 还是 21、被否方案（如继续留 8）的理由

7. 五个误区

误区	真相
"版本越高越好"	依赖不兼容时新版反而更慢（要绕坑）
"非 LTS 也能上生产"	半年停更
"强封装只是警告"	17 起默认拒绝对 JDK 内部的反射
"升级只改 pom"	构建、镜像、监控、依赖都要动
"虚拟线程能直接替换线程池"	要注意 pinning（同步阻塞）与生态适配（待核细节）

8. 自检（架构师版）

判据为什么是"依赖树能否抬到目标版本"而不是"新版特性多好"？
强封装带来什么具体故障？怎么兜底？
三档升级路径怎么选？
虚拟线程降低了哪类改造成本？
回滚方案里"镜像保留期"为什么重要？

9. 下一篇

S04-A02 · Excel 方案选型：POI vs FastExcel

版本基线定完，最后一篇做一个具体的选型：Java 处理 Excel 的两条路线。

本篇属于系列《S04 · Java 语言核心》。旧文来源：A-1716/A-2336；扩展点 E-S04-019。