Java 開發命名規範全攻略：包、類、方法、變量、常量、Javadoc 一網打盡

統一、清晰的命名規範是團隊協作與代碼可維護性的基石。本文依據《阿里巴巴 Java 開發手冊》、Google Java Style Guide 及業界通用慣例，系統梳理 Java 命名全景圖，涵蓋包、類、接口、方法、變量、常量、Javadoc 及其他文件命名，附帶反面教材與工具配置建議。

一、通用原則

• 可讀性優先：名字即文檔，拒絕拼音、無意義縮寫（如 `a`、`temp`、`flag`）。
• 駝峰命名法：
  • UpperCamelCase（帕斯卡）：類、接口、枚舉、註解類型。
  • lowerCamelCase：方法、參數、成員變量、局部變量。
• 全大寫 + 下劃線：常量（`static final`）、枚舉值。
• 全小寫 + 點分隔：包名。

二、包命名規範

2.1 基礎規則

• 全小寫，單詞間無分隔符：`com.company.project.module`
• 前綴為反轉域名：`com.alibaba`、`org.springframework`、`cn.mycompany`
• 禁止使用保留字、中文拼音、數字開頭。

2.2 分層架構包結構（推薦）

com.company.project
├── common          // 通用工具、常量、異常
├── config          // 配置類
├── moduleName      // 業務模塊
│   ├── controller  // Web 層（或 web、api）
│   ├── service     // 業務邏輯層
│   │   └── impl    // Service 實現
│   ├── dao         // 數據訪問層（或 repository、mapper）
│   │   └── mapper  // MyBatis Mapper 接口
│   ├── entity      // 實體類（或 domain、model、po）
│   ├── dto         // 數據傳輸對象
│   ├── vo          // 視圖對象
│   └── converter   // 對象轉換器
└── infrastructure  // 基礎設施（MQ、Redis、定時任務等）

2.3 反面教材

三、類/接口/枚舉命名

3.1 類命名

• 名詞或名詞短語：`UserService`、`OrderController`、`ThreadPoolExecutor`
• 實現類加 `Impl` 後綴：`UserServiceImpl`（接口為 `UserService`）
• 抽象類加 `Abstract`/`Base` 前綴：`AbstractUserService`
• 異常類以 `Exception` 結尾：`BusinessException`、`ParameterValidateException`
• 測試類以 `Test` 結尾：`UserServiceTest`

3.2 接口命名

• 名詞/形容詞/動詞均可，體現能力：`Serializable`、`Runnable`、`Comparable`、`UserRepository`
• 不加 `I` 前綴（C# 風格），不加 `Interface` 後綴。

3.3 枚舉命名

• 類名單數名詞：`OrderStatus`、`HttpMethod`
• 枚舉值全大寫下劃線：`PENDING_PAYMENT`、`GET`、`POST`

四、方法命名

4.1 通用規則

• 動詞或動詞短語開頭：`getUserById`、`saveOrder`、`calculateTotalAmount`
• 返回布爾值的判斷方法：`is`/`has`/`can`/`should` + 形容詞/名詞
  • `isValid()`、`hasPermission()`、`canAccess()`、`shouldRetry()`
• Getter/Setter：`get`/`set` + 屬性名（首字母大寫），布爾型 Getter 可用 `is`：`isEnabled()`

4.2 分層方法命名差異化

五、變量命名

5.1 通用變量（成員/局部/參數）

• lowerCamelCase：`userName`、`orderList`、`maxRetryCount`
• 拒絕單字母：除循環計數器 `i`/`j`/`k` 外，嚴禁 `a`、`b`、`c`、`temp`、`data` 等無意義名。
• 集合類變量：建議帶容器類型後綴：`userList`、`userSet`、`userMap`、`idToUserMap`
• 布爾型：`is`/`has`/`can`/`should` 開頭：`isDeleted`、`hasError`、`canProceed`

5.2 類型前綴（可選，團隊統一即可）

現代 IDE 類型提示完善，前綴法漸趨式微，推薦純語義命名。

5.3 靜態常量（static final）

• 全大寫 + 下劃線：`MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE`、`TIMEOUT_MILLIS`
• 枚舉值同規則。

六、Javadoc 規範

6.1 必須編寫 Javadoc 的場景

• 所有 public/protected 類、接口、枚舉、方法、字段。
• 異常類、註解類型、SPI 接口。

6.2 標準模板

/**
 * 類/接口簡述：一句話說明核心職責。
 * 

 * 詳細說明：使用場景、線程安全性、關鍵算法、擴展點等。
 * 
 *
 * @author 作者名
 * @version 1.0.0
 * @since 2024-01-15
 */
public class UserServiceImpl implements UserService {

    /**
     * 根據 ID 查詢用戶。
     *
     * @param userId 用戶唯一標識，必須 > 0
     * @return 用戶信息，不存在返回 null
     * @throws BusinessException 用戶狀態異常時拋出
     * @see UserRepository#findById(Long)
     */
    @Override
    public UserDTO getUserById(Long userId) {
        // 實現...
    }
}

6.3 常用標籤

七、其他文件命名

八、IDE 自動化配置建議

IntelliJ IDEA

1. Code Style：Settings → Editor → Code Style → Java → 命名規則，按本文規範配置。
2. File Template：Settings → Editor → File and Code Templates，預置 Javadoc 模板。
3. Save Actions：安裝 Save Actions 插件，保存自動格式化、優化導入、補全 Javadoc。
4. CheckStyle/SpotBugs：接入 CI 流水線，強制命名規範檢查。

九、快速檢查清單

• [ ] 包名全小寫、域名前綴、分層清晰
• [ ] 類名帕斯卡、名詞、職責單一可讀
• [ ] 方法名動詞開頭、分層語義區分
• [ ] 變量名語義清晰、拒絕單字母、布爾 is/has/can
• [ ] 常量全大寫下劃線、無魔法數字
• [ ] Public API 全覆蓋 Javadoc、參數/返回/異常完整
• [ ] 團隊統一 IDE 配置、CI 攔截不規範提交

命名規範無絕對標準，團隊內部統一、貫徹執行 才是關鍵。建議將本文作為團隊《Java 開發規範》命名章節的基礎版本，結合項目實際微調後落地。