以下是基于業(yè)界最佳實(shí)踐的 SpringBoot 項(xiàng)目命名規(guī)范總結(jié)，涵蓋項(xiàng)目、包、代碼及配置文件的命名規(guī)則：

一、項(xiàng)目命名規(guī)范

項(xiàng)目名稱(chēng)或者模塊名稱(chēng)都遵循這個(gè)規(guī)范：

全小寫(xiě)字母

• 避免操作系統(tǒng)路徑兼容性問(wèn)題（如Linux區(qū)分大小寫(xiě)）。

連字符分隔單詞

• 使用短橫線-連接多單詞（如user-management-system），禁止使用下劃線或空格。

描述性明確

• 直接體現(xiàn)項(xiàng)目功能（如payment-gateway而非project-001）。

二、包命名規(guī)范

反轉(zhuǎn)域名前綴

• 格式：com.組織名.項(xiàng)目模塊（如com.example.account）。

全小寫(xiě)字母+點(diǎn)分隔

• 包名中禁止使用大寫(xiě)字母或連字符（如錯(cuò)誤示例：com.example.userService）。
• 點(diǎn)分隔符之間有且僅有一個(gè)自然語(yǔ)義的英語(yǔ)單詞。包名統(tǒng)一使用單數(shù)形式（如應(yīng)用工具類(lèi)包名為com.alibaba.ei.kunlun.aap.util）

分層結(jié)構(gòu)清晰

• 按功能分層命名子包：

com.example.project
 ├── controller    # 請(qǐng)求入口層 
 ├── service       # 業(yè)務(wù)邏輯層（含impl實(shí)現(xiàn)類(lèi)包）
 ├── repository    # 數(shù)據(jù)訪問(wèn)層 
 ├── model         # 實(shí)體類(lèi)層 
 └── config        # 配置類(lèi)包   

三、類(lèi)與接口命名規(guī)范

當(dāng)一個(gè)接口有多個(gè)實(shí)現(xiàn)類(lèi)時(shí)，命名建議采用以下方式：

核心實(shí)現(xiàn)類(lèi)（默認(rèn)/主要實(shí)現(xiàn)）： 保持名詞+ServiceImpl命名（如 OrderServiceImpl）

其他實(shí)現(xiàn)類(lèi)： 采用名詞+功能描述+Impl格式，例如：

OrderServiceCacheImpl（帶緩存功能的實(shí)現(xiàn)） OrderServiceMockImpl（用于測(cè)試的Mock實(shí)現(xiàn)） OrderServiceAsyncImpl（異步實(shí)現(xiàn)版本）

特殊場(chǎng)景：

• 針對(duì)不同數(shù)據(jù)源的實(shí)現(xiàn)：OrderServiceJdbcImpl / OrderServiceNoSqlImpl
• 不同算法版本：OrderServiceV1Impl / OrderServiceV2Impl

這種命名方式能清晰體現(xiàn)：

• 實(shí)現(xiàn)類(lèi)與接口的歸屬關(guān)系（通過(guò) Service 后綴）。
• 具體實(shí)現(xiàn)的功能差異（通過(guò)中間描述詞）。
• 避免因簡(jiǎn)單編號(hào)導(dǎo)致的含義模糊問(wèn)題。

注意事項(xiàng)

類(lèi)名使用 UpperCamelCase 風(fēng)格，以下情形例外：DO/BO/DTO/VO/AO/PO/UID 等。只包含名詞，禁止包含動(dòng)詞，介詞或副詞。命名時(shí)要謹(jǐn)慎考慮類(lèi)的所在層級(jí)或顆粒度，禁止以數(shù)據(jù)字段的顆粒度單位去命名類(lèi)。

抽象類(lèi)命名使用 Abstract 或 Base 開(kāi)頭；實(shí)現(xiàn)類(lèi)以 Impl 為后綴；工具類(lèi)以 Util 為后綴；異常類(lèi)命名使用 Exception 結(jié)尾，測(cè)試類(lèi)命名以它要測(cè)試的類(lèi)的名稱(chēng)開(kāi)始，以 Test 結(jié)尾。枚舉類(lèi)名以Enum為后綴，枚舉成員名稱(chēng)需要全大寫(xiě)并以下劃線(_)分隔。類(lèi)名如果有復(fù)數(shù)含義，可以使用復(fù)數(shù)形式。比如 MessageUtils（此規(guī)則參考 spring 的框架結(jié)構(gòu)）。

如果模塊、接口、類(lèi)、方法使用了設(shè)計(jì)模式，在命名時(shí)要體現(xiàn)出具體模式。將設(shè)計(jì)模式體現(xiàn)在名字中，有利于閱讀者快速理解架構(gòu)設(shè)計(jì)思想。如果有使用模式，則以模式的名稱(chēng)為后綴，例如 Factory，Proxy，Observer 等。比如：public class OrderFactory;

POJO 類(lèi)中的任何布爾類(lèi)型的變量，都不要加 is 前綴，否則部分框架解析會(huì)引起序列化錯(cuò)誤。表達(dá)是與否的數(shù)據(jù)庫(kù)字段采用 is_xxx 的命名方式，所以需要在設(shè)置從 is_xxx 到 xxx 的映射關(guān)系。

接口中的方法和屬性不要加任何修飾符號(hào)（public 也不要加），保持代碼的簡(jiǎn)潔性，并加上有效的 Javadoc 注釋。盡量不要在接口里定義常量，如果一定要定義，最好確定該常量與接口的方法相關(guān)，并且是整個(gè)應(yīng)用的基礎(chǔ)常量。JDK8 中接口允許有默認(rèn)實(shí)現(xiàn)，那么這個(gè) default 方法，是對(duì)所有實(shí)現(xiàn)類(lèi)都有價(jià)值的默認(rèn)實(shí)現(xiàn)。

接口和實(shí)現(xiàn)類(lèi)的命名有兩套規(guī)則：

1）對(duì)于 Service 和 DAO 類(lèi)，基于 SOA 的理念，暴露出來(lái)的服務(wù)一定是接口，內(nèi)部的實(shí)現(xiàn)類(lèi)用 Impl 的后綴與接口區(qū)別。CacheServiceImpl 實(shí)現(xiàn) CacheService 接口。

2）如果是形容能力的接口名稱(chēng)，取對(duì)應(yīng)的形容詞為接口名（通常是 –able 結(jié)尾的形容詞）。AbstractTranslator 實(shí)現(xiàn) Translatable。

四、方法和變量命名規(guī)范

方法名、參數(shù)名、成員變量、局部變量都統(tǒng)一使用 lowerCamelCase 風(fēng)格。方法名參數(shù)名采用“動(dòng)詞+名詞”的形式。變量名只包含名詞，長(zhǎng)度不宜過(guò)長(zhǎng)（單詞個(gè)數(shù)建議不超過(guò)4），語(yǔ)義需清晰。方法名過(guò)長(zhǎng)時(shí)某些名詞可以采用縮寫(xiě)的形式，但禁止出現(xiàn)語(yǔ)焉不詳?shù)那闆r，例如 XXXHis，XXXCnd 等。

常量命名應(yīng)該全部大寫(xiě)，單詞間用下劃線隔開(kāi)，力求語(yǔ)義表達(dá)完整清楚，不要嫌名字長(zhǎng)。常量采用 static 修飾。非專(zhuān)屬常量，不使用唯一的一個(gè)常量類(lèi)來(lái)維護(hù)，按常量功能進(jìn)行歸類(lèi)與維護(hù)。

類(lèi)型與中括號(hào)緊挨相連來(lái)定義數(shù)組。定義整形數(shù)組，比如：int[] arrayDemo。

避免在子父類(lèi)的成員變量之間、或者不同代碼塊的局部變量之間采用完全相同的命名，使可理解性降低。

在常量與變量命名時(shí)，表示類(lèi)型的名詞放在詞尾，以提升辨識(shí)度。startTime / workQueue / nameList / TERMINATED_THREAD_COUNT。

五、配置文件命名規(guī)范

主配置文件

• application.yml（或.properties）。

多環(huán)境配置

通過(guò)-{profile}后綴區(qū)分環(huán)境：

• application-dev.yml：開(kāi)發(fā)環(huán)境
• application-prod.yml：生產(chǎn)環(huán)境 。

日志配置

• Logback：logback-spring.xml
• Log4j 2.x：log4j2-spring.xml（置于src/main/resources/）。

六、自定義 Starter 命名規(guī)范

七、接口 API 命名規(guī)范

業(yè)務(wù) API 接口和 OpenAPI 接口的命名規(guī)范都需要遵循 RESTful 設(shè)計(jì)風(fēng)格：

URL 路徑命名

• 小寫(xiě)字母與中劃線連接：路徑應(yīng)使用小寫(xiě)字母，單詞間用中劃線分隔（如/user-profile），避免下劃線或駝峰命名。
• 資源導(dǎo)向：路徑需體現(xiàn)資源層級(jí)（如/orders/{order-id}/items），避免包含動(dòng)詞，操作由HTTP方法（GET/POST等）體現(xiàn)。
• 復(fù)數(shù)形式：資源集合建議使用復(fù)數(shù)名詞（如/users），單個(gè)資源可通過(guò)路徑參數(shù)標(biāo)識(shí)（如/users/{id}）。

版本控制

• 路徑標(biāo)識(shí)版本：推薦在URL中顯式聲明版本（如/v1/products），便于后續(xù)迭代時(shí)兼容舊客戶端。
• 避免將版本號(hào)混入查詢參數(shù)或請(qǐng)求頭，以保持URL語(yǔ)義清晰。

參數(shù)命名

• 查詢參數(shù)：使用小寫(xiě)蛇形命名（如sort_by=create_time），明確描述過(guò)濾、排序等邏輯。
• 路徑參數(shù)：需與資源層級(jí)匹配（如/departments/{dept-id}），參數(shù)名需簡(jiǎn)潔且無(wú)歧義。

各層命名規(guī)約

A）Service / DAO 層方法命名規(guī)約：

• 1）獲取單個(gè)對(duì)象的方法用 get 做前綴。
• 2）獲取多個(gè)對(duì)象的方法用 list 做前綴，復(fù)數(shù)結(jié)尾，如：listObjects
• 3）獲取統(tǒng)計(jì)值的方法用 count 做前綴。
• 4）插入的方法用 save / insert 做前綴。
• 5）刪除的方法用 remove / delete 做前綴。
• 6）修改的方法用 update 做前綴。

B）領(lǐng)域模型命名規(guī)約：

• 1）數(shù)據(jù)對(duì)象：xxxDO，xxx 即為數(shù)據(jù)表名。
• 2）數(shù)據(jù)傳輸對(duì)象：xxxDTO，xxx 為業(yè)務(wù)領(lǐng)域相關(guān)的名稱(chēng)。
• 3）展示對(duì)象：xxxVO，xxx 一般為網(wǎng)頁(yè)名稱(chēng)。
• 4）POJO 是 DO / DTO / BO / VO 的統(tǒng)稱(chēng)，禁止命名成 xxxPOJO。

DO / PO / DTO / BO / VO / UID

• DTO（Data Transfer Object）：數(shù)據(jù)傳輸對(duì)象，Service 或 Manager 向外傳輸?shù)膶?duì)象。
• BO（Business Object）：業(yè)務(wù)對(duì)象，可以由 Service 層輸出的封裝業(yè)務(wù)邏輯的對(duì)象。
• Query：數(shù)據(jù)查詢對(duì)象，各層接收上層的查詢請(qǐng)求。注意超過(guò) 2 個(gè)參數(shù)的查詢封裝，禁止使用 Map 類(lèi)來(lái)傳輸。
• VO（View Object）：顯示層對(duì)象，通常是 Web 向模板渲染引擎層傳輸?shù)膶?duì)象。

八、數(shù)據(jù)庫(kù)命名規(guī)范

數(shù)據(jù)庫(kù)表達(dá)是與否概念的字段，必須使用 is_xxx 的方式命名，數(shù)據(jù)類(lèi)型是 unsigned tinyint（1 表示是，0 表示否）。注意：POJO 類(lèi)中的任何布爾類(lèi)型的變量，都不要加 is 前綴，所以，需要在設(shè)置從 is_xxx 到 Xxx 的映射關(guān)系。數(shù)據(jù)庫(kù)表示是與否的值，使用 tinyint 類(lèi)型，堅(jiān)持 is_xxx 的命名方式是為了明確其取值含義與取值范圍。

說(shuō)明：任何字段如果為非負(fù)數(shù)，必須是 unsigned。

正例：表達(dá)邏輯刪除的字段名 is_deleted，1 表示刪除，0 表示未刪除。

表名、字段名必須使用小寫(xiě)字母或數(shù)字，禁止出現(xiàn)數(shù)字開(kāi)頭禁止兩個(gè)下劃線中間只出現(xiàn)數(shù)字。數(shù)據(jù)庫(kù)字段名的修改代價(jià)很大，因?yàn)闊o(wú)法進(jìn)行預(yù)發(fā)布，所以字段名稱(chēng)需要慎重考慮。說(shuō)明：MySQL 在 Windows 下不區(qū)分大小寫(xiě)，但在 Linux 下默認(rèn)是區(qū)分大小寫(xiě)。因此，數(shù)據(jù)庫(kù)名、表名、字段名，都不允許出現(xiàn)任何大寫(xiě)字母，避免節(jié)外生枝。

表名不使用復(fù)數(shù)名詞。說(shuō)明：表名應(yīng)該僅僅表示表里面的實(shí)體內(nèi)容，不應(yīng)該表示實(shí)體數(shù)量，對(duì)應(yīng)于 DO 類(lèi)名也是單數(shù)形式，符合表達(dá)習(xí)慣。

禁用保留字，如 desc、range、match、delayed 等，請(qǐng)參考 MySQL 官方保留字。

主鍵索引名為 pk_字段名；唯一索引名為 uk_字段名；普通索引名則為 idx_字段名。

說(shuō)明：pk_即 primary key；uk_即 unique key；idx_即 index 的簡(jiǎn)稱(chēng)。

小數(shù)類(lèi)型為 decimal，禁止使用 float 和 double。說(shuō)明：在存儲(chǔ)的時(shí)候，float 和 double 都存在精度損失的問(wèn)題，很可能在比較值的時(shí)候，得到不正確的結(jié)果。如果存儲(chǔ)的數(shù)據(jù)范圍超過(guò) decimal 的范圍，建議將數(shù)據(jù)拆成整數(shù)和小數(shù)并分開(kāi)存儲(chǔ)。

如果存儲(chǔ)的字符串長(zhǎng)度幾乎相等，使用 char 定長(zhǎng)字符串類(lèi)型。

varchar 是可變長(zhǎng)字符串，不預(yù)先分配存儲(chǔ)空間，長(zhǎng)度不要超過(guò) 5000，如果存儲(chǔ)長(zhǎng)度大于此值，定義字段類(lèi)型為 text，獨(dú)立出來(lái)一張表，用主鍵來(lái)對(duì)應(yīng)，避免影響其它字段索引率。

表必備三字段：

id，create_time，update_time。說(shuō)明：其中 id 必為主鍵，類(lèi)型為 bigint unsigned、單表時(shí)自增、步長(zhǎng)為 1。create_time，update_time 的類(lèi)型均為 datetime 類(lèi)型，如果要記錄時(shí)區(qū)信息，那么類(lèi)型設(shè)置為 timestamp。

在數(shù)據(jù)庫(kù)中不能使用物理刪除操作，要使用邏輯刪除。

說(shuō)明：邏輯刪除在數(shù)據(jù)刪除后可以追溯到行為操作。不過(guò)會(huì)使得一些情況下的唯一主鍵變得不唯一，需要根據(jù)情況來(lái)酌情解決。

表的命名最好是遵循“業(yè)務(wù)名稱(chēng)_表的作用”。正例：alipay_task / force_project / trade_config / tes_question。

庫(kù)名與應(yīng)用名稱(chēng)盡量一致。

如果修改字段含義或?qū)ψ侄伪硎镜臓顟B(tài)追加時(shí)，需要及時(shí)更新字段注釋。

字段允許適當(dāng)冗余，以提高查詢性能，但必須考慮數(shù)據(jù)一致。

冗余字段應(yīng)遵循：

1）不是頻繁修改的字段。

2）不是唯一索引的字段。

3）不是 varchar 超長(zhǎng)字段，更不能是 text 字段。

比如各業(yè)務(wù)線經(jīng)常冗余存儲(chǔ)商品名稱(chēng)，避免查詢時(shí)需要調(diào)用商品服務(wù)獲取。

單表行數(shù)超過(guò) 500 萬(wàn)行或者單表容量超過(guò) 2GB，才推薦進(jìn)行分庫(kù)分表。說(shuō)明：如果預(yù)計(jì)三年后的數(shù)據(jù)量根本達(dá)不到這個(gè)級(jí)別，請(qǐng)不要在創(chuàng)建表時(shí)就分庫(kù)分表。

合適的字符存儲(chǔ)長(zhǎng)度，不但節(jié)約數(shù)據(jù)庫(kù)表空間、節(jié)約索引存儲(chǔ)，更重要的是提升檢索速度。

九、其他命名規(guī)范

所有編程相關(guān)的命名均不能以下劃線或美元符號(hào)開(kāi)始，也不能以下劃線或美元符號(hào)結(jié)束。

所有編程相關(guān)的命名嚴(yán)禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。正確的英文拼寫(xiě)和語(yǔ)法可以讓閱讀者易于理解，避免歧義。注意，即使純拼音命名方式也要避免采用。

代碼和注釋中都要避免使用任何人類(lèi)語(yǔ)言中的種族歧視性或侮辱性詞語(yǔ)。

杜絕完全不規(guī)范的英文縮寫(xiě)，避免望文不知義。

為了達(dá)到代碼自解釋的目標(biāo)，任何自定義編程元素在命名時(shí)，使用完整的單詞組合來(lái)表達(dá)。

十、總結(jié)

以上為個(gè)人經(jīng)驗(yàn)，希望能給大家一個(gè)參考，也希望大家多多支持腳本之家。

最新評(píng)論