Java 開發規範精華：命名、異常、日志、集合、併發與代碼組織 27 條鐵律

Java 開發規範精華版（27 條必遵鐵律）

好規範是團隊協作的潤滑劑，更是系統穩定的基石。本文提煉自實戰項目，涵蓋命名、異常、日志、集合、併發、代碼組織六大維度。

一、基本原則（強制）

1. 字符串拼接：循環/多次拼接必須用 StringBuilder（單線程）或 StringBuffer（多線程）。
2. 異常處理：
   — 禁止 catch (Exception e) { } 吞異常
   — 禁止 catch (Exception e) { e.printStackTrace(); } 只打印不處理
   — 推薦：catch (BizException e) { throw new RuntimeException(e); } 或拋轉換後的業務異常
   — 不知如何處理 → 向上拋出，由統一異常處理器攔截
3. 集合返回值：方法簽名必須帶泛型；Javadoc 標註何時返回 null、何時返回空集合。
4. 訪問控制：優先 private > protected > public；變量優先局部 > 實例 > 靜態；必須共享時用 ThreadLocal 避免併發問題。
5. 循環優化：避免循環內 new Object()、定義變量、try-catch；延後對象創建到最後使用時刻。
6. 註釋規範：邏輯複雜處用行註釋 //，禁用塊註釋 /* */；公開 API 必寫 Javadoc。
7. 命名規範：類名 PascalCase；方法/變量 camelCase；常量 UPPER_SNAKE；JSP 文件全小寫；Spring Bean id 類名首字母小寫；配置文件 xxx.bean.xml / xwork_xxx.xml。
8. 日志規範：禁 System.out.println；debug 級別守護 if (log.isDebugEnabled())；error 含完整堆棧與關鍵上下文。
9. Import & 格式化：提交前清理無用 import、統一格式化（IDE 快捷鍵）。
10. 單元測試：有業務邏輯的類必寫 JUnit 測試。
11. 國際化：FTL 模板無中文，鍵值放 Action_zh_CN.properties / Action_en_US.properties；編碼 UTF-8。
12. 文件/方法大小：文件 ≤ 2000 行，方法 ≤ 100 行（有效行），單一職責。
13. 作用域最小化：能局部勿實例，能實例勿靜態；必要時 ThreadLocal。
14. 異常轉換：盡可能處理或轉換，勿層層包裝 new Exception(e)。
15. 資源清理：需確定性清理的資源用 try-finally 或 try-with-resources。
16. 內部類：邏輯強相關（如事件監聽）可用內部類，享有外部類私有訪問權。
17. 封裝：字段私有，提供 getter/setter 保護不變約束。
18. 面向接口編程：優先 List/Set/Map 接口類型聲明，實現類可替換。
19. 集合選型：ArrayList 順序、HashSet 去重、HashMap 鍵值、LinkedList 隊列/棧；轉型為接口類型。
20. 數組 vs 集合：性能極致、大小固定用數組；動態擴容用集合。
21. 最小權限：private/protected 降低耦合，併發下保護不變性。
22. 後台禁用：try { } catch (Exception ex) { } 空 catch、new Exception() 拋裸異常。

二、類結構組織順序

1. 常量
2. 靜態字段
3. 實例字段
4. 構造器
5. 生命周期方法
6. 業務方法（按重要性/字母/關聯性排序）
7. 靜態方法
段與段之間空行分隔

三、變量聲明規範

• 成員變量 private，每行一個聲明（int a; int b;）
• 局部變量聲明即初始化，放在代碼塊開頭
• 數組聲明 Type[] name（非 Type name[]）
• for 循環變量可內聯 for (int i = 0; i < n; i++)

四、方法規範

• 參數 ≤ 5，超過封裝 DTO/VO
• 嵌套循環 ≤ 2 層
• 非必要不 public，最終類/方法加 final
• 接口方法默認 protected，跨模塊調用才 public

五、語言細節

• 避免變量遮蔽
• 常量前置比較："const".equals(var)、null == obj
• return 避免複雜表達式
• switch 必有 default

將以上規範內化為肌肉記憶，Code Review 時才能「一眼看出味道」，讓團隊代碼風格統一、質量在線。