服務API設計之——API命名規範

API命名規範

命名風格

---

面向資源

同RESTful命名風格

在大型系統中，常以」業務領域」視角進行模塊劃分，以達到業務」高內聚低耦合」的效果。

「業務領域」必有」數據對象」沉澱，從宏觀抽象的角度看，"數據對象"可統稱爲"資源"，」業務領域」就是業務相近的」資源」的集合。

"資源"必定是業務抽象後的對象：

1. 能夠是具體的數據對象：
   • 商品
   • 訂單
   • 合同
   • 發票
   • 採購計劃
   • etc
2. 能夠是抽象的對象概念：
   • 租戶
   • 用戶
   • 支付
   • 文件
   • 需求
   • etc

"業務領域"與"業務領域"之間的依賴，可理解爲是對"資源"操做(讀、寫、通知)的依賴。

因此，API做爲"業務領域"間溝通的手段，其應該(Should)以面向資源角度進行命名。

注：子資源，須要逐級索引命名，例如：修改-訂單-商品：updateOrderItem。

---

單一視角

• 參見單一視角原則

---

動賓風格

API應該(Should)以"動賓短語"風格命名。

例如：

1 2 3 4 5

xxx.xxx.xxx.OrderService // 上下文已涵蓋Order語義 Response<T> save(...) Response<T> updateItem(Long orderId, List<T> items)

1 2 3 4 5 6 7

xxx.xxx.xxx.WCService // 上下文未涵蓋Order語義 Response<T> saveOrder(...) Response<Boolean> removeOrder(Long orderId) Response<T> updateOrderItem(Long orderId, List<T> items) // 逐級索引子資源

---

統一術語

API命名統一」動詞」術語、」名詞」術語。優勢是能風格一致，經驗複用。

詳見政採雲API術語參考

注：統一術語的節奏，參考研發級術語規範逐步執行：業務內統1、業務領域內統1、平臺統一。

錯誤實踐-1：」商品」命名不統一

1 2 3 4

業務1：商品 -> item ✔️ 業務2：商品 -> items 業務3: 商品 -> product 業務4：商品 -> goods

錯誤實踐-2：」特性」命名不統一

1 2 3

業務1：特性 -> feature ✔️ 業務2: 特性 -> character 業務3：特性 -> rule

錯誤實踐-3：」金額」命名不統一

1 2 3

業務1：金額 -> amount ✔️ 業務2: 金額 -> money 業務3：金額 -> sum

錯誤實踐-4：」校驗」命名不統一

1 2 3

業務1：校驗 -> verify 業務2: 校驗 -> check ✔️ 業務3：校驗 -> test

錯誤實踐-5：」分頁」命名不統一

1 2 3

業務1：分頁 -> page 業務2: 分頁 -> paging✔️ 業務3：分頁 -> list

錯誤實踐-6：」建立」命名不統一

1 2 3

業務1：建立 -> save✔️ 業務2: 建立 -> create 業務3：建立 -> insert

錯誤實踐-7：」刪除」命名不統一

1 2 3 4

業務1：刪除 -> delete 業務2: 刪除 -> remove✔️ 業務3：刪除 -> disable 業務3：刪除 -> cancel

錯誤實踐-8：」檢索」命名不統一

1 2 3

業務1：搜索 -> query✔️ 業務2: 搜索 -> search 業務3：搜索 -> list

---

常見API命名參考

假設：未按資源劃分Service(上下文未界定資源域)的狀況

「XXX」指某一種資源，」xxx」指」XXX」下的子資源

分頁查詢

• 正確實踐

1	Response<Page<T>> pagingXXX(QueryDTO q) //用對象包裝查詢條件

• 錯誤實踐

1	Response<Page<T>> pagingXXX(String name, String code, Long orgId, Long creatorId, Integer pageNo, Integer PageSize)

以上錯誤實踐缺點：
一、對於調用方來講，不管以什麼條件查詢，都須要逐個條件傳參
二、API對擴展不友好，一旦想增長查詢條件，API就不兼容。

列表查詢

• 正確實踐

1	Response<List<T>> listXXX(...)

獲取單個詳情

• 正確實踐

1 2 3 4 5

Response<T> getXXX(Long id) 類同條件，用重載 Response<T> getXXX(String code)

• 錯誤實踐

1 2 3

Response<T> getXXXById(Long id) Response<T> getXXXByCode(String code)

說明：

1. API契約應該由」API名 + 入參」共同組成，而不是隻靠」API名」說明一切。
2. API方法支持獲取單個詳情的方式，能夠經過入參字段名自解釋。無需再用」By***」來額外標註。
3. 不帶」By***」聲明的方法語義上更具備擴展性。

建立

• 正確實踐

1	Response<T> saveXXX(...) //參照《阿里巴巴Java編碼規範》

刪除

• 正確實踐

1	Response<T> removeXXX(...) //參照《阿里巴巴Java編碼規範》

更新

• 正確實踐

1 2 3

Response<T> updateXXX(...) //參照《阿里巴巴Java編碼規範》 Response<T> updateXXXxxx(...) //更新主資源下的子資源

提審

• 正確實踐

1	Response<T> submitXXX(...)

審覈

• 正確實踐

1	Response<T> auditXXX(...)

退回（退回到流程中的某一步）

• 正確實踐

1	Response<T> returnXXX(...)

撤銷（退回到流程的第一步）

• 正確實踐

1	Response<T> cancelXXX(...)