Betreazen/java-knowledge

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 — 從「症狀 → 技術 → 來源」表格開始
依據 JEP 的 Java 17–28 語言功能、慣用寫法、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 個主要來源」](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
模組程式碼：客戶端/伺服器端與執行緒、註冊表、資料元件、方塊、實體、資料生成、編解碼器、網路、事件、Mixin、Access Wideners 與 Transformers、渲染、配置、世界生成、移植到新版本、審查清單	references/minecraft-mod-api.md — 在 26.x 中損壞了什麼，請參閱[「26.x 中損壞了什麼」](references/minecraft-mod-api.md#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 月的版本」](references/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 中損壞了什麼」](references/minecraft-mod-api.md#26.x 中損壞了什麼)
Minecraft：伺服器延遲 (MSPT、TPS)，如何找到原因並證明修復有效	minecraft-performance-testing.md → 「症狀 → 技術 → 來源」，工作順序請參閱 [pipeline.md → 「Minecraft 模組與插件」](references/pipeline.md#minecraft 模組與插件)
Minecraft：資料包、插件或模組；從頭開始建立 Paper 插件	minecraft-server-plugins.md → 「選擇：資料包、插件或模組」，「範本」

腳本 scripts/BenchCompare.java 會比較 JMH 在「之前」和「之後」的執行結果（基於其 JSON），並考慮執行之間的雜訊，如果出現迴歸則返回退出碼 1。無需建構即可執行：在 JDK 17+ 上使用 java BenchCompare.java <之前> <之後>。它在管線的第 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。