# ADR-0001：选择 Java 版本基线

- 状态：已接受
- 日期：2026-09-01
- 决策负责人：Java 架构学习项目维护者
- 评审人：示例工程维护者

## 背景

学习工程需要覆盖现代 Java 并发和 Spring 应用，同时让使用 Java 17 的读者能够理解迁移差异。代码示例必须由长期
支持版本编译，并能在 CI 中重复运行。

## 决策驱动因素

- 需要使用已经正式发布的虚拟线程。
- 依赖库需要具备成熟的 Java 21 支持。
- 示例应保留迁移到 Java 25 的路径。
- 不使用预览特性作为通用示例的必要条件。

## 备选方案

### 方案 A：Java 17

- 收益：现有企业项目采用广泛，兼容性风险低。
- 代价：不能使用正式版虚拟线程。
- 风险：现代并发教程需要额外运行时。
- 退出路径：通过编译和测试矩阵逐步迁移到 21。

### 方案 B：Java 21

- 收益：长期支持版本，包含正式版虚拟线程，生态支持成熟。
- 代价：Java 17 项目需要处理依赖和运行环境升级。
- 风险：部分遗留工具可能仍绑定旧版 JDK。
- 退出路径：保留 Java 17 兼容性说明，并建立升级检查表。

### 方案 C：Java 25

- 收益：当前长期支持版本，支持更多运行时和语言改进。
- 代价：部分组织和依赖的采用速度较慢。
- 风险：读者的 CI、IDE 或基础镜像可能尚未升级。
- 退出路径：先使用 21，单独验证 25，再提高最低基线。

## 决定

通用示例以 Java 21 为最低编译和运行基线。版本专题同时验证 Java 17 迁移和 Java 25 兼容性。

## 后果

### 正面后果

- 并发教程可以直接使用正式版虚拟线程。
- 示例使用稳定长期支持版本。
- Java 25 可以作为明确的升级目标单独验证。

### 负面后果

- 只安装 Java 17 的读者需要增加一个 JDK。
- 构建脚本和 IDE 必须显式选择 Java 21。
- 维护者需要验证关键示例在 Java 25 上的兼容性。

## 实施与验证

- 在 Maven 中设置 `maven.compiler.release=21`。
- 在 CI 中运行 Java 21 主任务，并为关键工程增加 Java 25 兼容任务。
- 在版本迁移文章中记录已知不兼容项和回滚方案。

## 重新评估条件

满足任一条件时重新评估：Java 21 依赖停止维护；主要框架提高最低版本；Java 25 在目标组织中完成生产验证；下一长期
支持版本发布并获得主要依赖支持。

## 关联决定

- 替代：无
- 被替代：无
- 相关 ADR：无