Java: 知识库与流水线

Java: 知识库与流水线 是做什么的？

本技能帮助你在任何领域编写、审查和优化 Java 代码。它包含三部分：

1. 知识库。 按类别归类的书籍、文章、演讲、文档、JEP、代码库和模式。每个来源都附有链接、作者、年份和阅读原因说明。
2. 工具链。 应安装哪些 JDK、构建工具和分析器，应运行哪些命令及其顺序。包含经过验证的 pom.xml、Gradle 和 CI 模板。
3. 流水线。 工作顺序：测试先于代码、质量检查、JMH 基准测试、审查、在知识库中查找解决方案，以及重新测量。

知识状态截至 2026 年 11 月：JDK 27（2026 年 9 月）为最新版本，JDK 25 为当前 LTS，JDK 21 和 17 为之前的 LTS，JDK 28 将于 2027 年 3 月发布。Maven 3.9.16 和 3.10.0（Maven 4 仍为 RC），Gradle 9.9，JUnit 6.1，Spring Boot 4.1，Quarkus 3.40，JMH 1.37。Minecraft：26.3 为最新版本（2026 年 9 月），26.4 在快照中；自 26.1 起，游戏不再混淆并需要 Java 25。

查看位置

任务	文件
新功能、重构或优化：工作顺序	references/pipeline.md
JDK 发行版和版本、安装、Maven 和 Gradle、插件、BOM、注解处理器、javac -Xlint、Error Prone、NullAway、SpotBugs、PMD、Spotless、OpenRewrite、依赖安全、JDK 工具、CI、模板	references/toolchain.md
JUnit 6、AssertJ、Mockito、Testcontainers、Spring Boot 切片、基于属性和契约测试、JaCoCo、PIT、不稳定测试	references/testing.md
代码慢或内存占用高：按症状查找技术、JMH、JFR、JIT、GC、启动与预热	references/performance.md — 从“症状 → 技术 → 来源”表格开始
Java 17–28 语言特性（按 JEP）、惯用法、null 与 Optional、异常、模式与反模式、安全、审查清单	references/idioms-patterns.md
项目结构、多模块构建、包与 JPMS、分层与六边形架构、DDD、ArchUnit、DI、API 演进、参考代码库	references/architecture.md
内存模型、executors、CompletableFuture、锁、虚拟线程、结构化并发、scoped values、响应式库、FFM API、JNI、Unsafe、Vector API	references/concurrency-native.md
服务端领域：Spring Boot、Quarkus、Micronaut、Helidon、REST 与 gRPC、JDBC、JPA 与 Hibernate、迁移、Kafka、可观测性、安全、容器与 Kubernetes	references/domains-server.md
其他领域：库发布、CLI 与 TUI、桌面、数据、ML 与 LLM 应用、游戏、嵌入式、WebAssembly、互操作、脚本	references/domains-client.md
阅读推荐、博客、演讲、播客、课程、俄语资源、分级学习路径	references/books.md。对于关于书籍的通用问题，从 “简短列表：20 个主要来源” 和 “分级阅读路径” 部分开始，按目录打开主题部分。文件很大，不要通读

Minecraft 分支（Java 版：模组和服务端插件，Minecraft 26.x 及最新的 1.21.x）：

任务	文件
开始模组：选择加载器（Fabric、NeoForge、Forge、Quilt）、游戏和 Java 版本、Loom 和 ModDevGradle、多加载器和多版本、发布到 Modrinth 和 CurseForge、构建模组包、CI、经过验证的模板	references/minecraft-modding.md
模组代码：端和线程、注册表、数据组件、方块、实体、数据生成、编解码器、网络、事件、混入、访问扩展器和转换器、渲染、配置、世界生成、迁移到新版本、审查清单	references/minecraft-mod-api.md — 26.x 中损坏的内容，请查看 “26.x 中损坏的内容” 部分
卡顿、TPS 和 MSPT、FPS、内存、启动慢；spark 和 JFR；世界基准测试 /tick sprint；GameTest 和单元测试；分析崩溃报告和模组冲突	references/minecraft-performance-testing.md — 从“症状 → 技术 → 来源”表格开始
服务器：数据包、插件或模组；Paper、Folia、Velocity、Spigot、Sponge、Minestom；Polymer；Geyser 和 ViaVersion；插件工程和模板	references/minecraft-server-plugins.md
文档及其时效性、如何阅读旧教程、课程、按类型划分的参考模组、社区、学习路径	references/minecraft-resources.md

每个参考指南都以目录开头。只阅读所需部分，不要通读文件。

常见问题及解答部分：

问题	部分
切换到 JDK 23+ 后，生成的类（Lombok、MapStruct、JMH）丢失，但构建成功；其他不明显的构建失败	toolchain.md → “陷阱：总结”
合并前使用哪个命令检查项目	toolchain.md → “最低质量检查”
在性能分析或基准测试中看到什么以及如何处理	performance.md → “症状 → 技术 → 来源”
如何编写不撒谎的基准测试	performance.md → “基准测试：JMH”
在 Windows、Linux 和 macOS 上使用什么进行性能分析	performance.md → “性能分析”
我们可以在当前 JDK 版本上使用某个语言特性吗	idioms-patterns.md → “语言版本：Java 17–28”
是否要将服务迁移到虚拟线程以及需要检查什么	concurrency-native.md → “虚拟线程”，对于 Spring Boot 4，另见 domains-server.md → “框架和运行时”
在高负载下选择哪种并发模型	concurrency-native.md → “按负载选择工具”
Spring Boot 4、Jackson 3、Hibernate 7 中发生了什么变化以及删除了什么	domains-server.md → “2026 年 11 月的版本”
慢端点、N+1、连接池	domains-server.md → “服务器性能：症状”
如何将项目拆分为模块并固定边界	architecture.md → “简短的默认规则”
某本书或版本是否存在	books.md → “已出版、早期访问和不存在的”
Minecraft：如何开始模组、带有 GameTest 和 CI 的现成项目	minecraft-modding.md → “模板”，选择加载器 — “默认堆栈”
Minecraft：旧教程或模组无法在 26.x 上构建（modImplementation、remapJar、ResourceLocation、Yarn）	minecraft-modding.md → “旧教程中的错误”，minecraft-mod-api.md → “26.x 中损坏的内容”
Minecraft：服务器卡顿（MSPT、TPS），如何找到原因并证明修复有帮助	minecraft-performance-testing.md → “症状 → 技术 → 来源”，工作顺序 — pipeline.md → “Minecraft 模组和插件”
Minecraft：数据包、插件或模组；从零开始的 Paper 插件	minecraft-server-plugins.md → “选择：数据包、插件还是模组”，“模板”

脚本 scripts/BenchCompare.java 比较 JMH “之前”和“之后”运行的结果（基于其 JSON），考虑运行间的噪声，并在出现性能回归时返回退出码 1。无需构建即可运行：java BenchCompare.java <之前> <之后>（需要 JDK 17+）。它在流水线的步骤 11 中使用。

对于 Minecraft，还有另外两个脚本：

• scripts/tick_sprint_bench.sh — 使用 /tick sprint 命令对整个服务器进行基准测试。结果以 JMH JSON 格式输出，因此可以使用相同的 BenchCompare.java 进行比较；
• scripts/EmptyStructure.java — 用于 GameTest 的空 .nbt 结构。在缺少内置空结构的 NeoForge 上需要。

脚本位于此 SKILL.md 旁边的 scripts/ 目录中。对于所有项目安装，路径为 ~/.claude/skills/java-knowledge/scripts/；对于项目内安装，路径为 .claude/skills/java-knowledge/scripts/。在参考指南的命令中使用此路径。

如何工作

对于超过一个方法大小的任务，请遵循 流水线：

1. 需求调研。
2. 计划和规格说明。
3. 子任务划分。
4. 测试先行。
5. 在 worktree 中隔离。
6. 基准测试。
7. 基线测量和分析。
8. 审查。
9. 在知识库中查找解决方案。
10. 优化。
11. 重新测量。

对于微小修改，使用同一文件中的简短模式即可：测试、代码、检查、审查。

在宣布工作完成之前，运行最低质量检查并显示其输出：

./mvnw -B -ntp verify                 # 编译（带 -Xlint -Werror、Error Prone 和 NullAway）、测试、Spotless、JaCoCo 阈值
./mvnw -B -ntp dependency:analyze
osv-scanner scan source -r .

对于 Gradle：./gradlew build、./gradlew buildHealth、osv-scanner scan source -r .。分析器和阈值应绑定到构建中 — 模板在 toolchain.md 中。如果项目中不存在，则运行现有的检查，并指出缺少哪些检查。如果某个工具未安装，请从 toolchain.md 中建议安装命令，而不是默默地跳过该步骤。

在进行优化时：

• 先测量，后修改。没有基线就无法判断代码是否变快。
• 使用 JMH 测量，而不是使用 System.nanoTime() 循环：JIT 会消除未使用的工作。在本地测量中，丢弃结果的计算看起来比实际快 14 倍。
• 分别使用“之前”和“之后”的单独 JVM 运行进行 5 次测量，并交替顺序（ABBA）。同一 JAR 的多次运行之间有 12-22% 的差异。
• 始终添加 -prof gc 并查看 gc.alloc.rate.norm（每次操作的字节数）：此指标几乎没有噪声。
• 一次只在一台机器上运行一个 JMH，并且在测量期间不要使机器负载其他工作。
• 根据 performance.md 中的症状查找技术，并在修改附近注明来源。
• 仅当基准测试显示显著收益并且测试保持绿色时才接受修改。

进行审查时，使用以下清单：

• idioms-patterns.md — 适用于任何代码；
• testing.md — 适用于测试；
• concurrency-native.md — 适用于多线程代码、虚拟线程和本地代码；
• domains-server.md — 适用于服务端代码、数据库和安全；
• domains-client.md — 适用于已发布的库；
• architecture.md — 适用于项目结构和模块边界。

知识库使用规则

• 引用来源。 推荐模式或优化时，提供参考指南中的链接。这样用户可以验证建议，并且解决方案不会显得随意。
• 注意标记。 [已过时] 表示该材料有替代品，并且在旁边已注明。[未验证] 表示该断言来自单个次要来源；在将其作为解决方案的基础之前，应进行交叉验证。
• 检查版本。 版本号截至 2026 年 11 月。2025-2026 年间发布了多个具有破坏性变更的主版本：Spring Boot 4 和 Spring Framework 7（重命名的启动器、已移除的 API）、Jackson 3（tools.jackson 包）、Hibernate 7、JUnit 6、Testcontainers 2（新的工件和包）、google-java-format 2。自 2025 年 6 月 30 日起，通过 OSSRH 发布已关闭。在做出重要决策之前，请查阅 Maven Central、文档和发行说明。
• 考虑目标 Java 版本。 在推荐新特性之前，请确认 maven.compiler.release 或 Gradle 中的 toolchain：scoped values、module imports 和紧凑源文件仅适用于 JDK 25，结构化并发仅在 JDK 28 中稳定，在此之前其 API 在每个版本中都会更改。未经明确同意，不要为生产环境推荐预览特性（--enable-preview）。版本表见 idioms-patterns.md。
• 直接说明空白。 如果知识库中没有答案，请如实说明，然后在官方文档中查找。不要将猜测当作知识库内容，也不要虚构书籍和版本：不存在的列表在 books.md 中。
• 遵循项目约定。 如果项目中已经使用了某种风格、构建工具、框架、库或架构，则知识库建议应在这些框架内应用，而不是覆盖它们。