java-coding-guide-prolisted

# Java 编码指南 面向日常 Java 开发的**编码约定助手**。每条规则「✗ 禁止 → ✓ 推荐」，覆盖 JDK 8~25+（LTS 锚定：8/11/17/21/25）。 ## 三条铁律 1. **栈中立**：库的选择**跟随项目既有依赖**，本指南不强加任何库；Spring 项目优先 Spring 生态自带能力（Jackson / RestTemplate / WebClient / SLF4J）。 2. **一域一默认**：每个场景只给唯一推荐（以项目既有栈为准），不列举「或 A 或 B」制造决策疲劳。 3. **版本门控**：先确认目标 JDK，高版本特性按门控使用——JDK 8 项目严禁 `var`/`record`/`switch 表达式`/文本块/`sealed`/`虚拟线程`。 ## 第 0 步：栈探测与适配（激活时先执行） 读 `pom.xml` / `build.gradle` 一次性探测（读不到则一次问全，勿分多轮）： 1. **目标 JDK**：`maven.compiler.release` / `<source>` / `sourceCompatibility`；读不到问用户「目标 JDK 版本是（8 / 11 / 17 / 21 / 25）？」。 2. **已有栈**：Spring 系（自带 Jackson/RestTemplate/WebClient/SLF4J）、Hutool、commons-lang3、Guava、Gson/Fastjson、OkHttp、Lombok、MapStruct。 3. **三条适配规则**： - 项目**已有**对应能力的库 → **跟随既有库**，不另引、不混用（一个项目一套字符串/集合工具）；仅当既有库缺该能力时补引，并在代码注释标注混用原因。 - **高风险能力缺失**且任务确实需要（见「风险分级与构件选择」）→ 触发 C-CHECK 询问是否引入。 - **低风险能力缺失**（判空/集合/随机数/日期等）→ 直接用 JDK 原生，**零打断、不询问**。 ## JDK 版本策略 **判据：目标 JDK ≥ 特性最低版本 → 可用；低于 → 禁用，改低版本写法。** 非 LTS 目标同样按版本比较，不另设档位。 | 特性 | 最低 JDK | |---|---| | Lambda / 方法引用 / `Optional` / `Stream` / `java.time` / `CompletableFuture` | 8（下限） | | `var`（仅局部变量） | 10 | | JDK 内置 `HttpClient` | 11 | | `switch` 表达式（箭头 / `yield`） | 14 | | 文本块 `"""` | 15 | | `record` / `Stream.toList()`（不可变）/ `instanceof` 模式匹配 | 16 | | `sealed` | 17 | | 虚拟线程 / `switch` 模式匹配 / `SequencedCollection` | 21 | | 未命名变量 `_` / Stream Gatherers / Scoped Values（22–24 转正，完整清单见 09） | 25 | > 22–24 转正特性统一按 25 门控；preview/incubator 不纳入。虚拟线程 + `synchronized` 在 21 会钉住载体线程（改 `ReentrantLock`