Java代碼開發規范（基于Claude Code與Google Java Style Guide）

1. 總則與目標

1.1 規范目的

本規范旨在為使用Claude Code進行Java開發的團隊提供一個統一、明確且專業的協作標準。其核心目標在于通過標準化代碼風格、開發流程和協作模式，顯著提升團隊的整體生產力、代碼質量和項目可維護性。在多人協作的軟件開發環境中，不一致的編碼風格和個人習慣往往是導致效率低下、溝通成本增加和代碼沖突的主要原因 。開發者可能會在代碼審查（Code Review）階段將寶貴的時間和精力浪費在討論格式問題而非邏輯缺陷上，合并代碼時也可能因格式差異產生大量無意義的沖突，新成員加入團隊時也需要額外的時間來適應不同的“個人風格” 。本規范通過強制執行一套基于業界最佳實踐（特別是Google Java Style Guide）的統一標準，旨在徹底消除這些摩擦，使團隊成員能夠將全部注意力集中在業務邏輯的實現和創新上，而非代碼格式的細枝末節。此外，規范的代碼是開發者專業素養的直接體現，它不僅提升了個人代碼的質量，更在團隊內部營造出一種追求卓越、注重細節的良好技術氛圍，對于開源項目而言，統一的風格還能極大地降低外部貢獻者的參與門檻，促進項目的健康、可持續發展 。

1.2 適用范圍

本規范適用于團隊內部所有使用Java語言進行開發的項目，特別是基于微服務架構的復雜系統，如電商平臺。它覆蓋了從代碼風格、命名約定到高級編程實踐、測試策略和團隊協作流程的方方面面。所有團隊成員，無論是新加入的初級開發者還是經驗豐富的資深工程師，在編寫、審查和維護Java代碼時，都必須嚴格遵守本規范。此外，當使用Claude Code進行代碼生成、重構或調試時，也應以本規范作為指導原則，確保AI生成的代碼與團隊手寫的代碼在風格和質量上保持高度一致。規范中涉及的具體技術棧，如Spring Boot、Lombok、AWS服務等，是團隊當前技術選型的體現，相關條款同樣適用于采用這些技術的所有模塊。通過在全團隊范圍內推行此規范，我們旨在建立一個高效、協同且高質量的開發文化。

1.3 核心理念

本規范的制定遵循以下核心理念：

1. 一致性優于完美：在所有代碼中保持統一的風格和結構，比追求個別代碼片段的完美實現更為重要。一致性降低了代碼的理解和維護成本，是團隊協作的基石。
2. 可讀性是第一要務：代碼是寫給人看的，機器只是順便執行。所有規范，從命名到結構，都應以提升代碼的可讀性和自解釋性為首要目標。
3. 擁抱現代工具與實踐：規范不僅包含傳統的代碼格式要求，更強調與現代開發工具和AI助手（如Claude Code）的結合，鼓勵使用Lombok、Optional、Stream API等現代Java特性來簡化代碼、減少錯誤。
4. 領域驅動與架構清晰：在復雜業務系統中，代碼結構應反映業務領域。規范倡導使用領域驅動設計（DDD）和清晰的架構模式（如六邊形架構），以確保代碼的可擴展性和業務邏輯的純粹性。
5. 質量內建與自動化：將質量保障融入開發的每個環節，通過高標準的測試覆蓋率、自動化代碼審查和持續集成（CI/CD）流程，確保代碼在合并前即達到高質量標準。

2. 開發環境與工具配置

2.1 基礎環境要求

2.1.1 Java版本

為確保項目能夠利用最新的語言特性、性能優化和安全更新，團隊統一采用Java 21作為標準開發版本 。Java 21是一個長期支持（LTS）版本，提供了穩定的平臺基礎和一系列現代語言特性，如記錄類（Record）、模式匹配（Pattern Matching）的增強以及虛擬線程（Virtual Threads）等，這些特性對于構建高性能、高并發的電商應用至關重要。所有開發環境、測試服務器和生產環境都必須統一使用此版本，以避免因版本不一致導致的兼容性問題。開發者應確保其本地IDE和構建工具（如Maven或Gradle）均配置為使用JDK 21進行編譯和運行。

2.1.2 構建工具

項目采用Maven作為主要的構建和依賴管理工具。Maven的標準化項目結構（Standard Directory Layout）和強大的依賴管理機制，有助于保持項目的一致性和可維護性。所有項目的pom.xml文件應遵循統一的配置規范，包括依賴版本管理、插件配置和構建配置文件（profiles）。對于依賴項，應明確定義其版本，并利用<dependencyManagement>在父POM中統一管理，以避免版本沖突。關鍵依賴項，如Spring Boot、AWS SDK等，其版本選擇需與團隊技術棧規劃保持一致，例如，統一使用Spring Boot 3.4.x和AWS SDK v2 。

2.1.3 IDE與插件

開發者可以自由選擇使用IntelliJ IDEA或Eclipse作為主要的集成開發環境（IDE）。為了確保代碼風格的一致性，所有IDE都必須安裝并配置相應的代碼格式化插件，以支持Google Java Style Guide。對于IntelliJ IDEA，可以直接導入intellij-java-google-style.xml配置文件 。此外，強烈推薦安裝以下插件以提升開發效率和代碼質量：

• Lombok Plugin: 用于支持Lombok注解的代碼生成和識別。
• SonarLint: 在編碼階段進行實時的靜態代碼分析，發現潛在的代碼異味、Bug和安全漏洞。
• Git Integration: 確保IDE內置的Git工具配置正確，以便進行版本控制操作。
• Docker Plugin: 用于本地容器化開發和測試，特別是與Testcontainers集成時。

2.2 Claude Code集成與配置

2.2.1 安裝與認證

Claude Code是團隊指定的AI編程助手，旨在通過自動化和智能建議提升開發效率。開發者需按照官方指南在本地環境中安裝并配置Claude Code。安裝完成后，需完成必要的認證流程以連接到Anthropic的服務。在團隊項目中，為了平衡效率與安全，建議在個人項目中或確保安全的前提下，可以使用--dangerously-skip-permissions模式，以避免在執行任務時反復確認權限，從而獲得更流暢的工作體驗 。然而，在處理敏感或生產代碼時，應謹慎使用此模式，并確保所有操作都在Git的版本控制之下，以便隨時回滾。

2.2.2 項目級配置：CLAUDE.md

CLAUDE.md文件是Claude Code理解項目上下文和團隊規范的核心。該文件應置于項目根目錄，并包含所有關鍵的開發指南和項目信息。一個精心配置的CLAUDE.md文件能將Claude Code從一個通用的AI助手，轉變為一個熟悉項目特定規范和架構的“團隊成員” 。該文件應至少包含以下內容：

• 項目概述：簡要描述項目的業務目標、架構風格（如微服務、DDD）和技術棧 。
• 代碼風格：明確指出遵循Google Java Style Guide，并提及具體的細節，如2個空格縮進。
• 技術棧與依賴：列出核心的框架和庫，如Spring Boot、Lombok、MapStruct、Resilience4j等，以及它們的用途 。
• 命名規范：詳細說明包、類、方法、變量和常量的命名約定。
• 架構原則：闡述項目采用的架構模式，如DDD的限界上下文、六邊形架構等。
• 測試策略：說明測試框架（如JUnit, AssertJ）、測試方法（如Given-When-Then）和覆蓋率要求。
• 錯誤處理：定義自定義異常的創建規則、全局異常處理機制以及錯誤響應的格式（如遵循RFC 7807）。
• 常用命令：提供構建、測試、運行等關鍵命令，方便Claude Code執行自動化任務。

2.2.3 團隊共享配置：.claude/team-standards.md

對于大型項目或跨團隊協作，單一的CLAUDE.md文件可能會變得臃腫且難以維護。在這種情況下，建議采用分層配置的策略。可以在項目根目錄下創建一個.claude/文件夾，并在其中放置多個按主題劃分的Markdown文件，例如team-standards.md、aws-guidelines.md、testing-strategy.md等 。team-standards.md文件可以包含更詳細的團隊約定，例如Git工作流、代碼審查清單、性能優化指南等。通過@語法，可以在與Claude Code的對話中引用這些文件，從而為其提供更具針對性的上下文信息 。這種模塊化的配置方式不僅使規范更易于維護和更新，也允許Claude Code在處理特定任務時加載最相關的上下文，從而提高其響應的準確性和效率。

3. 代碼風格規范（基于Google Java Style Guide）

3.1 源文件基礎

3.1.1 文件編碼與換行符

所有Java源文件必須使用UTF-8編碼，這是Google Java Style Guide的明確要求，也是現代軟件開發的國際標準 。使用UTF-8編碼可以確保代碼在全球范圍內的任何平臺和編輯器上都能正確顯示和處理各種字符，包括非ASCII字符。嚴禁使用其他編碼格式，如GBK或ISO-8859-1，以避免在跨平臺協作或國際化項目中出現亂碼問題。關于換行符，雖然Google Style Guide未明確規定，但為保持一致性，建議統一使用LF（Line Feed, \n） 作為行結束符，這在類Unix系統（如Linux, macOS）上是標準，并且與Git的默認行為一致。開發者應配置其IDE和文本編輯器，在保存文件時自動將換行符轉換為LF。

3.1.2 特殊字符處理

對于源代碼中的特殊字符，Google Java Style Guide提供了詳細的處理規則，旨在保證代碼的可讀性和可移植性 。

• 空白字符：除了用于縮進的空格和行尾的換行符，源文件中不應出現其他空白字符。特別是制表符（Tab） 被嚴格禁止用于縮進，必須使用空格。所有其他空白字符（如垂直制表符、換頁符）在字符和字符串字面量中必須使用轉義序列。
• 特殊轉義序列：對于具有預定義轉義序列的字符（如\b, \t, \n, \f, \r, \", \', \\），必須使用這些轉義序列，而不是其對應的八進制（如\012）或Unicode（如\u000a）轉義形式。這能顯著提升代碼的可讀性。
• 非ASCII字符：對于非ASCII字符，可以選擇直接使用實際的Unicode字符（如∞）或其Unicode轉義序列（如\u221e）。選擇哪種形式取決于哪種方式能讓代碼更易于閱讀和理解。然而，強烈建議在字符串和注釋之外避免使用Unicode轉義序列，因為這會使代碼難以理解。例如，String unitAbbrev = "μs";是最佳選擇，而String unitAbbrev = "\u03bcs"; // "μs"雖然允許，但可讀性較差。對于不可打印的字符，如字節順序標記（BOM），使用轉義序列并附上注釋是推薦的做法，例如：return '\ufeff' + content; // byte order mark 。

3.2 源文件結構

一個標準的Java源文件應按照嚴格的順序組織其內容，每個部分之間用一個空行分隔。這種結構化的組織方式有助于快速定位文件中的不同元素，提高代碼的可讀性 。

3.2.1 許可證信息

如果項目要求在源文件中包含許可證或版權信息，這些信息必須位于文件的最頂端。這通常是項目級別的統一要求，例如Apache License 2.0或MIT License。許可證信息應以注釋的形式存在，并遵循項目規定的標準格式。在添加許可證信息時，應確保其內容準確無誤，并與項目根目錄下的LICENSE文件保持一致。

3.2.2 包聲明

包聲明（package語句）必須緊跟在許可證信息之后。根據Google Java Style Guide，包聲明不允許換行，即使其長度超過了100個字符的行長度限制 。包名應全部使用小寫字母，并遵循反向的互聯網域名約定，例如com.company.project.module。這種命名方式確保了包名的全局唯一性，并能清晰地反映項目的模塊結構。

3.2.3 導入語句

導入語句（import語句）塊位于包聲明之后，類聲明之前。Google Style Guide對此有嚴格的規定：

• 禁止通配符導入：嚴禁使用星號（*）進行通配符導入，無論是靜態導入還是非靜態導入。必須顯式地導入每一個需要的類或靜態成員。這有助于提高代碼的清晰度，明確依賴關系，并避免在類路徑發生變化時出現命名沖突 。
• 不允許換行：與包聲明類似，單個導入語句不允許換行 。
• 導入順序與分組：導入語句應按以下順序分組，并用一個空行分隔：
  1. 所有靜態導入（import static）放在一個組。
  2. 所有非靜態導入（import）放在另一個組。
     在每個組內，導入語句應按其完全限定名的ASCII碼順序進行排序。例如，java.util.List應排在java.util.ArrayList之前，因為.的ASCII值小于; 。

3.2.4 類聲明

每個源文件只能包含一個頂層的類聲明。這是Google Style Guide的硬性規定，旨在保持文件的簡潔和專注。文件的名字必須與這個頂層類的名字完全一致（區分大小寫），并以.java作為擴展名 。類內部的成員（字段、方法、嵌套類等）應按照邏輯相關性進行組織，通常建議的順序是：靜態變量、實例變量、構造函數、公共方法、私有方法。

3.3 格式化規范

3.3.1 大括號使用

Google Java Style Guide對花括號（{}）的使用有明確的規定，旨在保持代碼結構的清晰和一致。對于if, else, for, do, while等控制結構，即使其代碼塊只有一條語句，也必須使用大括號。這可以防止在后續修改代碼時因忘記添加大括號而引入錯誤，是一種防御性編程的實踐。例如，應寫成if (condition) { doSomething(); }，而不是if (condition) doSomething();。對于類、方法和代碼塊，大括號的使用遵循K&R風格（Kernighan and Ritchie style），即左大括號與其聲明在同一行，右大括號獨占一行，除非它后面緊跟else或while等關鍵字。

3.3.2 縮進與行長度

• 縮進：Google Java Style Guide規定，每次進入一個新的代碼塊或塊級結構時，縮進增加兩個空格。這與許多其他風格指南（如Oracle的，使用4個空格）不同，是Google風格的一個顯著特點。當代碼塊結束時，縮進恢復到之前的級別。所有代碼和注釋都應遵循當前的縮進級別 。嚴禁使用制表符（Tab）進行縮進。
• 行長度：Java代碼的每行字符數限制為100個字符 。這個限制旨在確保代碼在各種屏幕尺寸和開發環境中都能舒適地閱讀，而無需水平滾動。雖然存在110個字符的“軟限制”，但超過120個字符的行應被強制換行。這個規則不適用于包聲明和導入語句，它們可以超出此限制 。

3.3.3 換行規則

當代碼行超過100個字符的限制時，需要進行換行。Google Style Guide提供了詳細的換行指導原則，核心目標是提高可讀性。通常，換行發生在運算符（如.、+、,）之后，而不是之前。例如，一個長方法調用鏈應該這樣換行：

MyObject myObject = someMethodCall(arg1, arg2)
    .anotherMethod()
    .finalMethod();

對于函數參數，如果換行，每個參數應獨占一行，并與第一個參數對齊。對于表達式，換行應發生在高優先級運算符之前，以清晰地表達運算的層次結構。

3.3.4 空白與分組括號

• 空白：在關鍵字（如if, for, catch）和左括號之間應有一個空格。在方法名和左括號之間不應有空格。在二元運算符（如+, =, ==）兩側都應有一個空格。在逗號后面應有一個空格，但在前面不應有。在類型轉換的右括號之后應有一個空格，例如：(String) obj。
• 分組括號：雖然分組括號（小括號）的優先級規則是明確的，但在復雜的表達式中，推薦使用額外的分組括號來明確運算順序，即使它們不是必需的。這可以消除歧義，使代碼更易于理解，是一種提升代碼可讀性的良好實踐 。

3.4 命名規范

3.4.1 包命名

包名應全部使用小寫字母，并采用反向的互聯網域名作為前綴，以確保其全局唯一性。例如，一個屬于company.com域的項目，其包名應以com.company開頭。后續部分應根據項目的模塊和功能進行細分，使用有意義的、能反映目錄結構的名稱，例如com.company.ecommerce.order.service。包名應簡潔且具有描述性，避免使用縮寫，除非該縮寫是廣為人知的（如util）。

3.4.2 類、接口與枚舉命名

類名、接口名和枚舉名都應使用PascalCase（大駝峰命名法），即每個單詞的首字母都大寫，不使用下劃線或其他分隔符 。名稱應具有高度的描述性，能夠清晰地表達其代表的實體或概念。例如，UserProfile, OrderService, PaymentStatus。對于接口，通常避免使用I前綴（如IUserService），而是使用描述其功能的名稱。對于抽象類，可以使用Abstract作為前綴（如AbstractOrderProcessor），但這并非強制要求 。

3.4.3 方法命名

方法名應使用camelCase（小駝峰命名法），即第一個單詞的首字母小寫，后續單詞的首字母大寫 。方法名通常是一個動詞或動詞短語，清晰地描述該方法執行的操作。例如，getUserName(), processOrder(), calculateFinalPrice()。對于返回布爾值的方法，其名稱應以is或has開頭，例如isValid(), hasPermission()。測試方法的命名可以更自由，但應遵循團隊約定，如使用should開頭的描述性短語（例如，shouldThrowExceptionWhenStockIsInsufficient）。

3.4.4 變量與常量命名

• 變量：實例變量、局部變量和方法參數都應使用camelCase命名法，與方法命名規則相同。變量名應是名詞或名詞短語，清晰地表達其存儲的數據。例如，userName, orderList, maxRetryCount。
• 常量：靜態常量（static final）應使用UPPER_SNAKE_CASE（全大寫，單詞間用下劃線分隔）命名法 。常量名應是名詞或名詞短語，清晰地表達其不變的值。例如，MAX_RETRY_ATTEMPTS, DEFAULT_TIMEOUT_MS, API_BASE_URL。

3.4.5 數據庫字段命名與映射

為了在Java代碼和數據庫之間建立清晰且一致的映射關系，我們采用以下命名約定：

• 數據庫字段：數據庫表中的字段名統一使用snake_case（小寫，單詞間用下劃線分隔）。例如，user_id, created_at, order_status。
• Java實體字段：對應的Java實體類中的字段名使用camelCase。例如，userId, createdAt, orderStatus。
• 映射：使用JPA（如Hibernate）或MyBatis等ORM框架時，必須明確配置這種命名映射關系。例如，在JPA中，可以使用@Column(name = "user_id")注解來指定數據庫字段名。這種約定使得數據庫模式（schema）和Java對象模型（domain model）在命名上保持各自的慣用風格，同時又能清晰地相互對應，提高了代碼和數據庫腳本的可讀性 。

3.5 Javadoc規范

3.5.1 格式要求

Javadoc是Java代碼文檔化的標準方式，其格式必須遵循嚴格的規范。每個Javadoc塊都以/**開始，以*/結束。注釋內容中的每一行都以*開頭，并且*應與開始的/**對齊。Javadoc標簽（如@param, @return, @throws）應放在注釋塊的末尾，并且每個標簽都應獨占一行。標簽的順序通常是@param, @return, @throws, @since, @deprecated。對于塊標簽（如@param），其描述文本應與標簽名對齊，形成統一的視覺格式。

3.5.2 內容要求

Javadoc的主要目的是解釋代碼的“是什么”、“為什么”以及“如何使用”，而不是簡單地重復代碼邏輯（“怎么做”）。

• 摘要片段：每個Javadoc注釋都應以一個簡潔的摘要片段開頭，該片段是一個沒有句號的短語或句子，能夠概括被注釋元素的核心功能。這個摘要片段在IDE的代碼提示和生成的HTML文檔中都會被突出顯示，因此其準確性至關重要 。
• 何處使用Javadoc：
  • 公共API：所有公共類、接口、方法以及公共和受保護的字段都必須有Javadoc。
  • 復雜邏輯：對于包含復雜算法或業務邏輯的私有方法，雖然不是強制要求，但強烈建議添加Javadoc來解釋其目的和實現思路。
  • 類級別：類級別的Javadoc應描述該類的職責、設計意圖以及如何使用它。可以包含使用示例或指向相關類的鏈接。
  • 方法級別：方法級別的Javadoc應描述其功能、參數含義（@param）、返回值（@return）以及可能拋出的異常（@throws）。對于@throws標簽，應解釋在什么條件下會拋出該異常。
• 內容質量：Javadoc應使用清晰、準確的語言。避免使用模糊不清的詞語。對于代碼中的特殊處理、設計決策或已知的局限性，都應在Javadoc中進行說明。

4. 現代Java編程實踐

4.1 語言特性應用

4.1.1 Lombok庫的使用規范

Lombok是一個強大的Java庫，通過注解處理器在編譯期自動生成樣板代碼（如getter、setter、構造函數等），從而顯著減少代碼冗余，使實體類（POJO）更加簡潔和易讀。在團隊項目中，我們鼓勵并規范使用Lombok，但必須遵循以下準則：

• 常用注解：
  • @Data: 這是一個復合注解，等同于@Getter @Setter @ToString @EqualsAndHashCode @RequiredArgsConstructor。在簡單的數據載體（DTO/VO）中，可以優先使用@Data。
  • @Builder: 強烈推薦使用此注解來創建對象的構建器模式。它提供了一種類型安全且可讀性高的方式來構建復雜對象，尤其是在參數較多的情況下。
  • @RequiredArgsConstructor: 此注解會生成一個包含所有final字段和@NonNull注解字段的構造函數。這是依賴注入和不可變對象模式的推薦做法。
• 避免使用的注解：
  • @AllArgsConstructor: 應避免使用此注解，除非有明確的理由。它會生成一個包含所有字段的構造函數，這可能導致在添加新字段時破壞現有代碼的兼容性，并且對于包含大量字段的類，構造函數會變得難以使用。相比之下，@Builder或@RequiredArgsConstructor是更安全、更靈活的選擇 。
• 注意事項：使用Lombok時，團隊成員的IDE必須安裝相應的插件以確保代碼提示和編譯正常。同時，需要確保構建服務器（如Jenkins）的編譯環境也正確配置了Lombok。

4.1.2 Optional的使用原則

java.util.Optional是Java 8引入的一個容器對象，用于表示一個值可能存在也可能不存在。它的設計初衷是為了更好地處理null值，避免臭名昭著的NullPointerException。在團隊中，我們優先使用Optional<T>替代可能為null的返回值 。這已經成為一種強制性的編程實踐，因為它能明確地告知調用者該方法可能不返回結果，從而迫使其進行顯式的處理。

• 作為返回值：當一個方法可能因為某些原因無法返回預期的對象時，應返回Optional<T>而不是null。例如，findUserById方法應返回Optional<User>。
• 使用方法：調用者必須使用Optional提供的方法（如isPresent(), ifPresent(), orElse(), orElseGet(), map(), flatMap()）來處理結果。這避免了忘記進行null檢查的風險。
• 避免濫用：Optional不應被用作類的字段，因為它本身不是可序列化的，并且會增加內存開銷。它也不應用于方法的參數，因為這會使調用變得繁瑣。其主要應用場景是作為方法的返回值。
• 示例：

  // 不推薦
  public User findUserById(Long id) {
      // ... 查找邏輯
      return user; // 可能返回null
  }
  
  // 推薦
  public Optional<User> findUserById(Long id) {
      // ... 查找邏輯
      return Optional.ofNullable(user);
  }
  

4.1.3 Stream API的最佳實踐

Java 8引入的Stream API為處理集合（Collection）提供了一種聲明式的、函數式的編程風格，它可以使復雜的集合操作變得更加簡潔、易讀和高效。本規范鼓勵在合適的場景下積極使用Stream API來替代傳統的for循環和if條件判斷。Stream API的核心優勢在于它將“做什么”（what）與“如何做”（how）分離，開發者只需關注數據處理的邏輯，而無需關心底層的迭代和狀態管理細節。例如，對一個用戶列表進行過濾、轉換和排序的操作，使用Stream API可以寫成：List<String> userNames = users.stream().filter(u -> u.getAge() > 18).map(User::getName).sorted().collect(Collectors.toList());。這段代碼清晰地表達了處理流程，其可讀性遠勝于等價的for循環實現。在使用Stream API時，應遵循一些最佳實踐：首先，盡量使用方法引用（Method Reference），如User::getName，它比lambda表達式更簡潔。其次，合理組合中間操作（如filter, map, sorted）和終端操作（如collect, forEach, reduce），以構建高效的處理管道。再次，注意Stream的惰性求值特性，終端操作是觸發整個流水線執行的關鍵。最后，對于簡單的迭代操作，如果性能是首要考慮因素，傳統的for循環可能仍然是更好的選擇。因此，應根據具體場景權衡使用，在提升代碼表達力和可維護性的同時，也要關注其對性能的影響。

4.2 架構與設計原則

4.2.1 領域驅動設計（DDD）

領域驅動設計（DDD）是一種軟件開發方法，它強調將業務領域作為軟件設計的核心。在大型復雜項目中，采用DDD可以幫助團隊更好地理解業務需求，并構建出高內聚、低耦合的系統。團隊鼓勵在項目中應用DDD的核心概念：

• 限界上下文（Bounded Context） ：將系統劃分為不同的限界上下文，每個上下文都有其獨立的領域模型和通用語言（Ubiquitous Language）。
• 實體（Entity）和值對象（Value Object） ：區分具有唯一標識的實體和沒有唯一標識的值對象。
• 聚合根（Aggregate Root） ：將一組相關的實體和值對象組織成一個聚合，并通過聚合根來管理聚合內部的一致性。
• 領域服務（Domain Service） ：將不屬于任何實體或值對象的領域邏輯封裝在領域服務中。
• 倉儲（Repository） ：為聚合根提供持久化機制，將領域模型與數據訪問層解耦。

4.2.2 六邊形架構

六邊形架構（Hexagonal Architecture），也稱為端口和適配器（Ports and Adapters）架構，是一種將業務邏輯與外部依賴（如數據庫、Web框架、消息隊列等）解耦的架構模式。在六邊形架構中，核心業務邏輯位于中心，外部依賴通過端口和適配器與核心進行交互。這種架構模式具有以下優點：

• 可測試性：可以輕松地用模擬對象（Mock）替換外部依賴，從而對核心業務邏輯進行單元測試。
• 可替換性：可以方便地替換外部依賴的實現，例如，將MySQL數據庫替換為MongoDB，而無需修改核心業務邏輯。
• 清晰的邊界：明確了核心業務邏輯和外部依賴之間的邊界，使代碼結構更清晰。

4.2.3 事件驅動通信

在微服務架構中，服務之間的通信是一個關鍵問題。團隊鼓勵使用事件驅動通信來實現服務之間的解耦。當一個服務完成某個操作后，它會發布一個事件，其他對該事件感興趣的服務可以訂閱并處理這個事件。這種通信方式具有以下優點：

• 松耦合：服務之間不直接調用，而是通過事件進行通信，從而降低了服務之間的耦合度。
• 可擴展性：可以方便地添加新的服務來訂閱和處理事件，而無需修改現有服務。
• 容錯性：即使某個服務暫時不可用，事件也可以在消息隊列中緩存，等服務恢復后再進行處理。

在Java項目中，可以使用Spring Cloud Stream、Apache Kafka等框架來實現事件驅動通信。

4.3 錯誤處理與日志記錄

4.3.1 自定義異常

在構建復雜的業務系統時，僅僅依賴Java標準庫提供的通用異常（如IllegalArgumentException、IllegalStateException）往往不足以精確地表達業務領域中的特定錯誤情況。因此，本規范要求團隊根據具體的業務領域，創建和使用自定義異常（Custom Exception）。自定義異常的核心價值在于其語義化，一個精心命名的異常類能夠清晰地告知調用者發生了什么類型的錯誤，而無需深入閱讀異常消息。例如，在一個電商系統中，當用戶嘗試購買庫存不足的商品時，拋出一個InsufficientStockException遠比拋出一個通用的RuntimeException或IllegalStateException更有意義。創建自定義異常時，應遵循以下原則：首先，異常類名應以Exception結尾，并準確描述錯誤場景，如PaymentFailedException、UserNotAuthorizedException。其次，自定義異常應提供多種構造函數，至少包括一個無參構造函數和一個接收錯誤消息字符串的構造函數，還可以提供一個接收Throwable cause的構造函數，以便進行異常鏈的傳遞，保留原始異常信息，這對于調試和問題排查至關重要。最后，應根據錯誤的性質決定是繼承自Exception（受檢異常）還是RuntimeException（非受檢異常）。通常，對于可以預期且調用者應該處理的錯誤，使用受檢異常；對于編程錯誤或運行時無法恢復的錯誤，使用非受檢異常。

4.3.2 全局異常處理

在基于Spring Boot等現代框架構建的Web應用中，采用全局異常處理機制是保持代碼整潔和提供一致錯誤響應的關鍵。本規范要求，所有REST API的異常處理都應通過一個集中的組件來完成，而不是在每個控制器（Controller）方法中重復編寫try-catch塊。在Spring框架中，可以通過@ControllerAdvice（或@RestControllerAdvice）注解的類來實現全局異常處理。這個類可以包含多個使用@ExceptionHandler注解的方法，每個方法負責處理一種或一類特定的異常。例如，可以有一個方法專門處理所有ValidationException，另一個方法處理所有自定義的業務異常，還有一個方法作為兜底，處理所有未被捕獲的Exception。這種集中式處理的好處是多方面的：首先，它極大地減少了代碼冗余，避免了在每個API端點重復相同的錯誤處理邏輯。其次，它確保了無論錯誤在何處發生，客戶端收到的錯誤響應格式都是統一的，這極大地提升了API的可用性和可預測性。最后，它使得錯誤處理邏輯（如記錄日志、發送告警通知）的修改和維護變得非常簡單，只需在一個地方進行修改即可。全局異常處理器應該負責將捕獲的異常轉換為標準化的錯誤響應對象，并設置合適的HTTP狀態碼，然后返回給客戶端。

4.3.3 錯誤響應標準

為了向API的消費者提供一致、清晰且機器可讀的錯誤信息，本規范規定，所有REST API的錯誤響應都必須遵循一個統一的標準。我們推薦采用RFC 7807標準，即“Problem Details for HTTP APIs”。該標準定義了一個JSON格式的錯誤響應體，包含一系列標準化的字段，用于描述錯誤詳情。一個符合RFC 7807標準的錯誤響應體通常包含以下字段：type（一個指向錯誤文檔的URI，用于解釋該類型錯誤的含義）、title（錯誤的簡短、人類可讀的摘要）、status（HTTP狀態碼）、detail（針對此特定錯誤實例的、人類可讀的詳細解釋）、instance（一個指向錯誤發生具體資源的URI）。例如，當用戶請求一個不存在的訂單時，服務器應返回一個HTTP 404狀態碼，并附帶如下JSON響應體：{ "type": "https://api.claude.com/errors/not-found", "title": "Resource Not Found", "status": 404, "detail": "Order with ID 12345 could not be found.", "instance": "/api/orders/12345" }。采用這種標準化格式的好處在于，客戶端可以編寫通用的錯誤處理邏輯來解析這些響應，例如，可以根據type字段來決定采取何種恢復策略，或者將detail字段直接展示給最終用戶。這遠比返回一個任意的、非結構化的錯誤消息要好得多，后者往往需要客戶端進行脆弱的字符串匹配來理解錯誤原因。

4.3.4 日志記錄規范

日志記錄是軟件系統可觀測性的基石，對于問題排查、性能分析和安全審計至關重要。本規范要求，所有日志記錄都必須遵循一套嚴格的標準，以確保日志的有效性和可用性。首先，日志框架應統一使用SLF4J（Simple Logging Facade for Java）作為API，并結合Logback或Log4j2作為具體的實現。這提供了靈活性，并允許在不修改代碼的情況下切換日志實現。其次，日志級別必須被正確使用：ERROR用于記錄系統遇到的嚴重問題，可能導致功能中斷；WARN用于記錄潛在的問題或非預期的狀態，但系統仍能繼續運行；INFO用于記錄重要的業務事件或系統狀態變更；DEBUG用于記錄詳細的調試信息，通常在開發和測試環境中開啟；TRACE用于記錄最詳細的信息，如方法調用的入參和出參，僅在深度排查問題時使用。再次，日志消息必須是清晰、有意義的，避免記錄無意義的“到達此處”之類的日志。最重要的是，在分布式系統中，為了能夠關聯一個請求在多個服務間的調用鏈路，必須在日志中記錄一個唯一的追蹤ID（Trace ID） 或關聯ID（Correlation ID） 。這個ID應在請求進入系統時生成，并在整個調用鏈中傳遞。最后，必須嚴格遵守安全規范，禁止在日志中記錄任何敏感信息，如用戶密碼、信用卡號、個人身份信息（PII）等。

5. 開發流程與團隊協作

5.1 分支管理策略

5.1.1 主分支保護

為了確保項目的穩定性和可發布性，本規范對主分支（通常命名為main或master）實施嚴格的保護策略。主分支是項目的“唯一事實來源”，其上的代碼必須始終處于可部署、可發布的狀態。因此，任何開發者都不得直接向主分支提交代碼。所有代碼變更都必須通過Pull Request（PR）或Merge Request（MR）的方式，經過代碼審查和自動化測試后，才能被合并到主分支。為了實現這一點，需要在代碼托管平臺（如GitHub, GitLab, Bitbucket）上配置分支保護規則。這些規則應至少包括：禁止直接推送（push）到主分支；所有PR必須經過至少一名其他團隊成員的審查并獲得批準；所有PR必須通過CI/CD流水線中的所有質量門（如單元測試、集成測試、代碼風格檢查、安全掃描等）。此外，還可以配置要求PR與主分支保持同步，即在合并前，PR分支必須包含主分支的最新代碼，這有助于及早發現集成沖突。通過這種保護機制，可以最大限度地減少因直接提交而引入的回歸bug，確保主分支的代碼質量，并為持續部署（CD）提供一個可靠的基礎。

5.1.2 功能分支與修復分支

為了支持并行開發和高效的協作，本規范采用基于分支的開發模型。所有新功能的開發、缺陷的修復以及實驗性的工作都必須在獨立的分支上進行，而不是直接在主分支上操作。分支的命名應遵循一個清晰、一致的約定，以便于團隊成員理解其用途。推薦的命名規范如下：對于新功能開發，使用feature/前綴，后跟功能描述，例如feature/user-authentication或feature/shopping-cart。對于缺陷修復，使用bugfix/前綴，例如bugfix/login-page-error或bugfix/memory-leak-in-parser。對于緊急的生產環境熱修復，可以使用hotfix/前綴，例如hotfix/disable-broken-feature。對于實驗性或探索性的工作，可以使用experiment/或spike/前綴。這種命名約定使得分支列表一目了然，便于管理和追蹤。當一個功能或修復完成后，開發者應創建一個Pull Request，請求將其分支合并回主分支。在PR被審查和批準后，應使用“Squash and Merge”或“Rebase and Merge”策略進行合并，以保持主分支提交歷史的整潔和線性。合并完成后，應及時刪除已合并的功能分支，以避免分支列表變得臃腫和混亂。

5.2 代碼審查（Code Review）

5.2.1 審查流程

代碼審查是保障代碼質量、促進知識共享和團隊協作的核心環節。本規范定義了一套標準的代碼審查流程，所有代碼變更都必須遵循此流程。流程始于開發者完成功能開發或缺陷修復，并在獨立的功能分支上進行充分的本地測試。隨后，開發者需要將本地分支推送到遠程倉庫，并在代碼托管平臺（如GitHub）上創建一個Pull Request（PR）。PR的標題和描述應清晰、簡潔地說明本次變更的目的、主要修改內容以及任何需要審查者特別注意的點。創建PR后，系統會自動觸發CI/CD流水線，執行預定義的自動化檢查，包括單元測試、集成測試、代碼風格檢查和安全漏洞掃描等。只有通過所有自動化檢查的PR，才能進入人工審查階段。開發者需要邀請至少一名或多名團隊成員作為審查者。審查者將對代碼進行詳細的審查，關注點包括代碼邏輯的正確性、性能、安全性、可讀性以及是否符合團隊的編碼規范。審查者可以在PR中發表評論、提出問題或建議。開發者需要根據審查意見進行修改，并推送新的提交到同一分支，這些提交會自動更新到PR中。當所有審查者都批準了PR，并且所有自動化檢查都通過后，PR即可被合并到主分支。

5.2.2 審查標準與檢查清單

為了確保代碼審查的有效性和一致性，本規范提供了一份詳細的審查標準與檢查清單。審查者在進行代碼審查時，應參照此清單，系統地評估代碼變更。這份清單涵蓋了多個維度，確保代碼的全面質量。

類別	檢查項	說明
功能性	代碼是否實現了預期的功能？	審查者需要理解需求，并驗證代碼邏輯是否能正確滿足這些需求。
	是否存在潛在的邏輯錯誤或邊界條件處理不當？	需要特別關注循環、條件判斷、異常處理等邏輯。
性能	代碼是否存在性能瓶頸？	例如，是否存在低效的算法、不必要的數據庫查詢或資源浪費。
	對于超過100行的代碼變更，是否進行了性能影響評估？	大范圍的修改可能對系統性能產生顯著影響，需要特別關注。
安全性	代碼是否通過了安全掃描？	所有變更都必須通過自動化安全工具的檢查，確保沒有引入已知漏洞。
	是否存在潛在的安全風險？	例如，SQL注入、跨站腳本（XSS）、敏感信息泄露（如密碼、密鑰硬編碼）等。
可讀性與可維護性	代碼是否易于理解？	方法、變量命名是否清晰？代碼結構是否清晰？注釋是否充分且準確？
	代碼是否遵循了團隊的編碼規范？	包括命名規范、格式規范、Lombok使用規范等。
	方法長度是否適中（建議不超過40行）？	過長的方法通常意味著職責不單一，應考慮拆分。
測試	代碼是否包含了相應的單元測試或集成測試？	所有新功能和重要的缺陷修復都應附有測試用例。
	測試用例是否覆蓋了主要的邏輯路徑和邊界條件？	測試覆蓋率應達到團隊設定的標準（例如80%）。
設計	代碼是否符合項目的整體架構設計？	例如，是否遵循了領域驅動設計（DDD）的原則，是否避免了不恰當的依賴關系。
	是否避免了代碼重復？	鼓勵代碼復用，遵循DRY（Don't Repeat Yourself）原則。

審查者應在PR的評論中明確指出發現的問題，并給出具體的改進建議。對于嚴重的問題，應標記為“必須修復”（Required）；對于建議性的改進，可以標記為“可以考慮”（Nice to have）。

5.2.3 Claude Code在審查中的應用

Claude Code可以作為代碼審查流程中的一個強大輔助工具，幫助審查者提高效率并發現潛在問題。在創建PR后，可以指示Claude Code對變更進行初步審查。Claude Code可以執行以下任務：

• 自動化規范檢查：根據CLAUDE.md和.claude/team-standards.md中定義的規則，檢查代碼是否符合團隊的編碼規范，包括命名、格式、Lombok使用等。
• 潛在問題識別：識別代碼中可能存在的邏輯錯誤、性能問題、安全漏洞風險（如硬編碼的敏感信息）或不良設計模式。
• 生成審查摘要：為PR生成一份結構化的審查摘要，概述變更內容、潛在風險點以及是否符合規范，為人工審查者提供一個良好的起點。
• 建議改進：針對發現的問題，提供具體的代碼修改建議或重構方案。

然而，必須明確的是，Claude Code的審查結果不能替代人工審查。它應被視為一個“第一遍過濾器”，幫助審查者聚焦于更復雜、更需要人類判斷的邏輯和架構問題。最終的質量把關和批準決策必須由人類開發者做出。

5.3 質量門（Quality Gates）

5.3.1 測試覆蓋率要求

測試覆蓋率是衡量代碼質量的一個重要指標，它反映了代碼被測試用例覆蓋的程度。為了確保新功能和代碼修改的可靠性，本規范設定了明確的測試覆蓋率要求。所有包含業務邏輯的代碼變更，其單元測試覆蓋率必須達到或超過80%。這意味著，在提交Pull Request之前，開發者需要編寫足夠的單元測試，以確保新增或修改的代碼行有至少80%被執行到。這一要求旨在強制開發者進行充分的測試，從而在開發早期發現并修復潛在的缺陷。CI/CD流水線中會集成代碼覆蓋率分析工具（如JaCoCo），在每次構建時自動計算并報告覆蓋率。如果PR的覆蓋率低于設定的閾值，CI/CD流水線將失敗，PR將無法被合并。

5.3.2 安全漏洞掃描

安全性是軟件質量不可或缺的一部分。所有代碼變更在合并前都必須通過自動化的安全漏洞掃描。CI/CD流水線中應集成至少一種靜態應用安全測試（SAST）工具，如SonarQube、Checkmarx或GitHub Advanced Security。這些工具會自動掃描代碼，檢測常見的安全漏洞，如SQL注入、跨站腳本（XSS）、不安全的反序列化、硬編碼的密碼和密鑰等。掃描結果將作為質量門的一部分，任何被識別為“關鍵（Critical）”或“高（High）”級別的安全漏洞都必須被修復，否則PR將被拒絕合并。這確保了主分支的代碼庫始終保持在一個較高的安全基線上。

5.3.3 性能與文檔檢查

除了功能和安全性，性能和文檔也是質量門的重要組成部分。

• 性能檢查：對于涉及性能敏感路徑的代碼變更（如數據庫查詢、API調用、算法實現），CI/CD流水線中應包含性能測試。可以使用JMeter、Gatling等工具進行自動化性能測試，并與基線性能指標進行對比。如果新代碼導致性能顯著下降（例如，響應時間增加超過10%），則PR應被標記為需要審查和優化。
• 文檔檢查：代碼和文檔應保持同步。對于公共API的變更，必須更新相應的API文檔（如OpenAPI/Swagger規范）。對于復雜的業務邏輯或架構決策，應在代碼中添加清晰的注釋或在項目文檔中進行說明。CI/CD流程可以包含一個檢查步驟，確保與代碼變更相關的文檔也已更新。例如，可以檢查PR的描述中是否包含“文檔已更新”的聲明，或者通過工具檢查代碼注釋的覆蓋率。

5.4 持續集成與部署（CI/CD）

5.4.1 自動化構建與測試

持續集成（CI）是現代軟件開發的核心實踐，旨在通過自動化的方式頻繁地集成代碼變更，并快速發現問題。本規范要求所有項目都必須有一個配置完善的CI/CD流水線。該流水線應在每次代碼提交（Push）或Pull Request創建時自動觸發。其核心任務包括：

1. 自動化構建：使用Maven或Gradle等工具，在干凈的環境中（如Docker容器）拉取最新代碼，并執行完整的構建過程，包括編譯、打包等。
2. 自動化測試：運行所有層級的測試，包括單元測試、集成測試和端到端測試。測試必須在隔離的環境中進行，以確保結果的可復現性。可以使用Testcontainers等工具來啟動和管理測試所需的依賴服務（如數據庫、消息隊列）。
3. 代碼質量檢查：執行靜態代碼分析、代碼風格檢查、安全漏洞掃描等，確保代碼符合團隊的質量標準。
   只有當所有步驟都成功通過后，代碼變更才能被視為“可集成”的，并進入下一階段的部署流程。

5.4.2 部署模式

持續部署（CD）是將通過CI驗證的代碼自動部署到生產環境的過程。為了平衡發布速度與系統穩定性，團隊應采用靈活、可靠的部署模式。

• 藍綠部署（Blue-Green Deployment） ：這是一種實現零停機時間部署的常用模式。它維護兩個完全相同的生產環境（藍環境和綠環境）。在任何時候，只有一個環境（例如，藍環境）處理用戶流量。新版本的應用被部署到非活動環境（綠環境），并在那里進行最終的測試。一旦驗證通過，流量將從藍環境切換到綠環境。如果出現問題，可以立即將流量切回藍環境，實現快速回滾。
• 金絲雀發布（Canary Release） ：這種模式下，新版本的應用首先被部署到一小部分服務器或用戶（“金絲雀”）。通過監控這部分用戶的反饋和系統指標，來評估新版本的穩定性。如果沒有發現問題，再逐步擴大新版本的部署范圍，直到覆蓋所有用戶。這種方式可以將新版本可能帶來的風險限制在最小范圍內。
• 滾動更新（Rolling Update） ：這是Kubernetes等容器編排平臺默認的部署策略。它逐步用新版本的應用實例替換舊版本的實例，直到所有實例都更新完畢。這種方式可以節省資源，但部署過程相對復雜，回滾也需要一定時間。

5.4.3 回滾策略

無論采用何種部署模式，都必須有一個清晰、快速的回滾策略，以應對生產環境中可能出現的緊急情況。

• 自動化回滾：CI/CD流水線應配置自動化回滾機制。例如，在部署后的一段時間內，持續監控關鍵性能指標（如錯誤率、響應時間）。如果這些指標出現異常并超過預設閾值，系統應自動觸發回滾操作，將應用恢復到上一個穩定版本。
• 手動回滾：除了自動化回滾，還應提供簡單、可靠的手動回滾機制。例如，在藍綠部署中，只需將流量切換回舊環境即可。在金絲雀發布中，可以停止向新版本引流。運維團隊應熟悉回滾流程，并定期進行演練，確保在緊急情況下能夠快速響應。

6. 測試策略

6.1 測試層次與類型

為了確保軟件質量，團隊應采用多層次的測試策略，覆蓋從單個組件到整個系統的不同范圍。

6.1.1 單元測試

單元測試是測試策略的基石，它專注于測試代碼中最小的可測試單元（通常是單個方法或類）。單元測試的目標是快速、獨立地驗證業務邏輯的正確性。為了達到這個目標，所有外部依賴（如數據庫、文件系統、網絡服務）都應被模擬（Mock）或存根（Stub）所替代。團隊應使用JUnit 5作為主要的單元測試框架，并結合Mockito來創建和管理模擬對象。單元測試應遵循FIRST原則：Fast（快速執行）、Independent（相互獨立）、Repeatable（可重復）、Self-Validating（通過斷言自我驗證）、Timely（及時編寫）。所有新編寫的業務邏輯都必須附有相應的單元測試，并且測試覆蓋率應達到團隊設定的標準（如80%）。

6.1.2 集成測試

集成測試用于驗證多個組件或服務之間是否能正確地協同工作。與單元測試不同，集成測試會涉及真實的外部依賴。在Java項目中，集成測試通常用于測試數據訪問層（Repository）與數據庫的交互、服務層與外部API的通信等。為了確保測試環境的可復現性和隔離性，團隊推薦使用Testcontainers庫。Testcontainers可以在測試運行時自動啟動和管理輕量級的、一次性的容器化服務，如PostgreSQL、Redis、Kafka等。這使得開發者可以在一個與生產環境非常接近的環境中運行集成測試，而無需手動搭建和維護復雜的測試基礎設施。

6.1.3 端到端測試

端到端（End-to-End, E2E）測試是從用戶的角度出發，模擬真實用戶場景，對整個應用系統進行測試。它驗證的是系統的所有組件（包括前端、后端、數據庫、第三方服務等）是否能作為一個整體正常工作。E2E測試通常通過自動化工具（如Selenium、Cypress）來模擬用戶在瀏覽器上的操作。雖然E2E測試的編寫和維護成本較高，但它對于驗證核心業務流程的正確性至關重要。團隊應優先為最關鍵、最高頻的用戶路徑編寫E2E測試，并將其集成到CI/CD流水線中，在預發布環境中執行。

6.2 測試規范

6.2.1 測試結構（Given-When-Then）

為了使測試代碼結構清晰、易于理解，所有測試用例都應遵循Given-When-Then的結構模式。這是一種行為驅動開發（BDD）的風格，它將測試分解為三個部分：

• Given (前置條件) ：設置測試的初始狀態，包括創建被測試對象、準備測試數據、配置模擬對象的行為等。
• When (執行操作) ：執行被測試的特定操作或觸發被測試的方法。
• Then (驗證結果) ：對操作的結果進行斷言，驗證其行為是否符合預期。這包括檢查返回值、驗證對象狀態的變化、確認與模擬對象的交