服務API設計之——API設計原則

你是否也感同身受？

1. 對接XX業務時，XX業務具有的功能和API全靠跑業務負責人那反覆逐個詢問、確認。用哪一個API；怎麼用；有沒有限制；等等
2. 各個業務間，甚至同一業務內，API風格不統一。
   • API命名：按天然語義全翻譯的；按屬性角度定義的；按操做角度定義的；動賓、非動賓的；複數、非複數的；等等
   • API入參：帶Map的；相同語義字段名稱不同；
   • API出參：有包裝Resoponse的；直接返回結果數據的；相同數據，返回格式和字段名稱有差異的；
   • 錯誤信息：直接返回中文提示的；返回提示信息編碼的；返回異常類型的；等等
3. XX業務API性能方面未知。
4. 隨着業務的演進，開放的API持續在增長，但類同的不少

API編碼規範迫在眉睫

---

優秀API的特質

1. 自解釋
   • 從API自己一眼就能看懂API是幹什麼的，支持的用法，適用的場景，異常的處理等
2. 易學習
   • 有完善的文檔，以及提供儘量多的示例和可copy－paste的代碼。
3. 易使用
   • 功能強大，但使用簡單。不增長調用方的使用成本（例如要求業務方用API時須要額外的配置和依賴），不暴露覆雜的細節、冗長的使用流程給調用方感知。調用方只作最小的感知和最少的傳參。
4. 難誤用
   • 優秀的API可使有經驗的開發直接使用API而不須要閱讀文檔。
   • 充分的靜態檢查、動態校驗、顯式的異常說明、有效的錯誤提示。

---

ZCY API 設計原則

1. 充分原則

不是隨便一個功能就要有個接口，也不是隨便一個需求就要加個接口。

每新建一個接口，要有充分的理由和考慮，即這個接口的存在是十分有意義和價值的。無心義的接口不只增長了維護的難度，更重要是對於程序的可控性的大大下降，接口也會十分臃腫。

2. 單一視角原則

設計接口時，分析的角度要統一。不然會形成接口結構的混亂。例如：不要一會以角色的角度設計，一下子就要以功能的角度設計。

推薦：以」屬性對象 + 行爲」的視角定義API

3. 單一功能原則

每一個API接口應該只專一一件事，並作好。產品概念簡單、關係清楚。功能模棱兩可，諸多特殊邏輯的API確定不是個優雅的API，且會形成功能相似重複的API。

注：若是API它很難命名，那麼這或許是個很差的徵兆，好的名稱能夠驅動開發、而且只需拆分與合併模塊便可。

功能大而全的API在靈活性、簡單性方面確定捉襟見肘。定義API的粒度以前，建議先將業務分領域、劃邊界，以此來提取業務對象，而後再根據業務對象用例來設計單一功能的API。

好比：查詢會員，可能除了查詢會員表外還要獲取該會員的其餘必要信息，但不要在查詢會員的同時還有修改權限等相似的其餘業務功能，應該分紅兩個接口執行。

4. 簡單原則

接口設計簡單、清晰。API執行的功能能夠很豐富、很強大，但API聲明和用法必定要儘可能的簡單，不能將功能的豐富經過複雜的用法來實現，這會致使API功能不單一，演進不可控。

最終的評審要看API的簡單易用程度。

• 你寫的例子，能不能讓你的代碼看起來更簡單？
• 你是否是強迫調用方關注/提供他們不在意的選項/配置？
• 有沒有毫無價值的額外步驟？

編寫的代碼必定要易於讀、易於理解，這樣別人纔會欣賞，也可以給你提出合理化的建議。相反，如果繁雜難解的程序，其餘人老是會避而遠之的。

5. 抽象原則

API的入參、出參所述的對象、屬性，必定是按業務特性進行抽象後的實體。誤將底層數據模型概念如實的反應到API上。抽象API、抽象對象實體更宏觀，具備更好的適用性、兼容性、擴展性。

6. 兼容擴展原則

對擴展開放，對修改關閉。保證API的向後兼容。

擴展參數應當是便利的，保證後續相似的需求，能夠在已有的API上經過兼容擴展的方式實現。

7. 最小驚訝原則

代碼應該儘量減小讓讀者驚喜。業務API只需根據需求來設計便可，不須要刻意去設計一下複雜無用、華而不實的API，以避免弄巧成拙。

8. 低耦合原則

API應該減小對其餘業務代碼的依賴關係。低耦合每每是完美結構系統和優秀設計的標誌。

耦合的種類：

• 代碼實現業務逆向調用。
• 條件邏輯依賴耦合。例如：此API在處理國稅網超訂單類型時，須要額外發送結算支付憑證上傳的事件MQ出來。
• 耦合API無關的業務行爲。例如：採購計劃鏈路日誌API被調用時，如果項目採購委託單的狀況，須要額外調用公告的API拉取鏈路信息，新建成爲一條此委託單的一條鏈路日誌。

9. 正交原則

正交性是指改變某個特性而不會影響到其餘的特性。

API之間的功能應該成正交性，無功能重合。API之間應該是互相補充的關係。

10. 易測試原則

對於API調用者而言，API應該是可被測試且易於被測試的。測試API不須要依賴額外的環境、容器、配置、公共服務等。

對可測試友好的API也是可被有效集成測試的前提。

11. 統一原則

API要具有統一的命名、統一的入/出參規範、統一的異常規範、統一的錯誤碼規範、統一的版本規範等。

統一規範的API優勢：

• 易於被框架集成、處理
• 有助於API調用方、API提供方開發經驗複用
• 避免犯錯，避免誤用