您现在的位置：程式碼之家 >> 編程語言 > >> Java 程式設計 >> Java 相關知識

Java 命名規範完整指南：從源文件到變量的系統性規範

編輯：Java 相關知識

統一的命名規範是代碼可讀性、可維護性的基石。本文依據 Sun/Oracle 官方《Code Conventions for the Java Programming Language》、Google Java Style Guide 及阿里巴巴開發手冊，系統梳理 Java 命名全景規範，涵蓋源文件、包、類/接口、常量、變量、方法、參數及補充細節，附帶 IDE 自動化配置建議。

一、源文件命名

規則：文件名必須與文件中定義的 public 類名完全一致（大小寫敏感）。
示例：`UserService.java` ↔ `public class UserService`
原因：編譯器依賴文件名查找類定義，不一致將導致編譯失敗或 IDE 警告。

二、包命名

全小寫：所有字母小寫，單詞間無分隔符。
前綴：反轉域名（`com`、`org`、`net`、`edu`、`gov`、`cn` 等）或 ISO 3166 國家代碼。
層級：按組織內部規範劃分：`com.company.project.module.layer`
示例：`com.alibaba.fastjson`、`org.springframework.boot.autoconfigure`、`cn.mycompany.project.user.dao`
導入順序：標準庫 → 第三方庫 → 本地包；同包通配符 `*` 合併；`import` 置於 `package` 之後。

三、類/接口命名

類型	規則	示例	備註
類	名詞，UpperCamelCase	UserService、ThreadPoolExecutor、ArrayList	簡潔、描述性強
異常類	以 Exception 結尾	BusinessException、ParameterValidateException
接口	名詞/形容詞/動詞，UpperCamelCase	Serializable、Runnable、Comparable、UserRepository	可加 able/ible/er 後綴表能力
實現類	接口名 + Impl	UserServiceImpl	區分接口與實現
抽象類	Abstract/Base 前綴	AbstractUserService
枚舉	單數名詞，UpperCamelCase	OrderStatus、HttpMethod	值全大寫下劃線
註解類型	UpperCamelCase	Override、Deprecated、Autowired

四、常量命名

規則：全大寫，單詞間下劃線分隔（`SNAKE_CASE`）。
語義：名字應賦予業務含義，禁用魔法數字。
示例：`MAX_RETRY_COUNT`、`DEFAULT_PAGE_SIZE`、`TIMEOUT_MILLIS`、`HTTP_STATUS_OK`
特例：Java 標準庫顏色常量（`Color.RED`）未強制全大寫，但自定義常量嚴格執行。

五、變量命名

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

規則：lowerCamelCase，首字母小寫，後續單詞首字母大寫。
語義：見名知意，拒絕無意義縮寫（`temp`、`data`、`obj`、`flag`）。
集合變量：建議帶容器後綴：`userList`、`userSet`、`idToUserMap`、`userNameSet`
布爾型：`is`/`has`/`can`/`should` 開頭：`isValid`、`hasPermission`、`canExecute`、`shouldRetry`
循環計數器：`i`/`j`/`k` 僅限小範圍循環，嵌套超 2 層改用語義名。
臨時/拋棄變量：`i`/`j`/`k`/`m`/`n`（整型）、`c`/`d`/`e`（字符型），用完即棄。

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

類型	前綴	示例
byte	byt	bytBuffer
char	chr	chrGrade
short	sht	shtYear
int/Integer	int / n	intCount / nCount
long/Long	lng	lngCreateTime
float/Float	flt	fltRate
double/Double	dbl	dblAmount
boolean/Boolean	bln / is	blnFlag / isDeleted
String	str	strUserName
自定義類	類名首字母小寫	userService、orderDTO

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

5.3 靜態變量（非 final）

全大寫下劃線：`USER_LIST`、`CONFIG_MAP`（視同常量風格）
若為可變集合，建議加 `MUTABLE_` 前綴警示：`MUTABLE_CACHE_MAP`

六、方法命名

規則：lowerCamelCase，首個單詞動詞，後續單詞首字母大寫。
核心原則：方法名表達「做什麼」，而非「怎麼做」。

類別	命名模式	示例	禁用/避免
Getter	get + 屬性名（首字母大寫）	getUserName()、getAge()
布爾 Getter	is/has/can/should + 形容詞/名詞	isValid()、hasError()、canAccess()	getValid()
Setter	set + 屬性名	setUserName()、setAge()
DAO/Repository	insert/delete/update/select/count/find/exists	insertUser()、findById()、existsByEmail()	業務動詞
Service	業務動詞	createOrder()、calculatePrice()、exportReport()	CRUD、Web詞彙
Controller	Web 語義	register()、login()、submit()、download()	CRUD、Service內部詞
通用業務	動詞 + 名詞	openFile()、addAccount()、calculateTotal()	do/process/handle 等模糊詞

七、方法參數命名

同普通變量規則：lowerCamelCase、語義清晰。
盡可能與目標字段同名：`setUserName(String userName)`
避免單字母、縮寫、無意義名。

八、補充細節與最佳實踐

8.1 類中常用方法命名模式

構造器：參數遞增順序（少參數優先）：`User()`、`User(String name)`、`User(String name, int age)`
toString()：每個類建議重寫，格式 `ClassName{field=value, ...}`，便於調試/日誌。
equals/hashCode：成對重寫，滿足契約；推薦 IDE 生成或 Lombok `@EqualsAndHashCode`。
main() 測試方法：類底部保留 `public static void main(String[] args)` 單元測試代碼，不影響生產構建。

8.2 循環變量與數組

循環計數器：`i`/`j`/`k` 或 `counter`/`index`
數組命名：`elementType[]` 形式：`int[] scores`、`String[] names`、`byte[] buffer`

8.3 導入包順序規範

package com.company.project.module;

import java.io.*;
import java.util.List;
import java.util.Map;

import com.alibaba.fastjson.JSON;
import org.springframework.stereotype.Service;

import com.company.project.common.util.StringUtils;
import com.company.project.module.entity.User;