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

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

項目名稱或者模塊名稱都遵循這個規(guī)范：

全小寫字母

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

連字符分隔單詞

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

描述性明確

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

二、包命名規(guī)范

反轉(zhuǎn)域名前綴

• 格式：com.組織名.項目模塊（如com.example.account）。

全小寫字母+點分隔

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

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

• 按功能分層命名子包：

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

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

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

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

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

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

特殊場景：

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

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

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

注意事項

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

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

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

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

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

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

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

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

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

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

常量命名應(yīng)該全部大寫，單詞間用下劃線隔開，力求語義表達完整清楚，不要嫌名字長。常量采用 static 修飾。非專屬常量，不使用唯一的一個常量類來維護，按常量功能進行歸類與維護。

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

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

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

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

主配置文件

• application.yml（或.properties）。

多環(huán)境配置

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

• application-dev.yml：開發(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è)計風(fēng)格：

URL 路徑命名

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

版本控制

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

參數(shù)命名

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

各層命名規(guī)約

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

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

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

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

DO / PO / DTO / BO / VO / UID

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

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

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

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

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

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

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

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

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

說明：pk_即 primary key；uk_即 unique key；idx_即 index 的簡稱。

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

如果存儲的字符串長度幾乎相等，使用 char 定長字符串類型。

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

表必備三字段：

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

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

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

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

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

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

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

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

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

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

3）不是 varchar 超長字段，更不能是 text 字段。

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

單表行數(shù)超過 500 萬行或者單表容量超過 2GB，才推薦進行分庫分表。說明：如果預(yù)計三年后的數(shù)據(jù)量根本達不到這個級別，請不要在創(chuàng)建表時就分庫分表。

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

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

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

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

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

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

為了達到代碼自解釋的目標，任何自定義編程元素在命名時，使用完整的單詞組合來表達。

十、總結(jié)

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

最新評論