設計一個高質量的 API 介面

你是否也感同身受？

• 對接XX業務時，XX業務具備的功能和API全靠跑業務負責人那反覆逐個詢問、確認。用哪個API；怎麼用；有沒有限制；等等
• 各個業務間，甚至同一業務內，API風格不統一。
• API命名： 按自然語義全翻譯的；按屬性角度定義的；按操作角度定義的；動賓、非動賓的；複數、非複數的；等等
• API入參： 帶Map的；相同語義欄位名稱不一樣；
• API出參： 有包裝Resoponse的；直接返回結果資料的；相同資料，返回格式和欄位名稱有差別的；
• 錯誤資訊： 直接返回中文提示的；返回提示資訊編碼的；返回異常型別的；等等
• XX業務API效能方面未知。
• 隨著業務的演進，開放的API持續在增加，但類同的很多

API編碼規範迫在眉睫

優秀API的特質

自解釋

• 從API本身一眼就能看懂API是幹什麼的，支援的用法，適用的場景，異常的處理等

易學習

• 有完善的檔案，以及提供儘可能多的示例和可copy－paste的程式碼。

易使用

• 功能強大，但使用簡單。不增加呼叫方的使用成本（例如要求業務方用API時需要額外的配置和依賴），不暴露覆雜的細節、冗長的使用流程給呼叫方感知。呼叫方只做最小的感知和最少的傳參。另外，搜尋公眾號前端技術精選後臺回覆“大禮包”，獲取一份驚喜禮包。

難誤用

• 優秀的API可以使有經驗的開發直接使用API而不需要閱讀檔案。
• 充分的靜態檢查、動態校驗、顯式的異常說明、有效的錯誤提示。

API 設計原則

1. 充分原則

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

每新建一個介面，要有充分的理由和考慮，即這個介面的存在是十分有意義和價值的。無意義的介面不僅增加了維護的難度，更重要是對於程式的可控性的大大降低，介面也會十分臃腫。

2. 單一視角原則

設計介面時，分析的角度要統一。否則會造成介面結構的混亂。例如：不要一會以角色的角度設計，一會兒就要以功能的角度設計。

推薦：以"屬性物件 + 行為"的視角定義API

3. 單一功能原則

每個API介面應該只專注一件事，並做好。產品概念簡單、關係清楚。功能模稜兩可，諸多特殊邏輯的API肯定不是個優雅的API，且會造成功能類似重複的API。

注：如果API它很難命名，那麼這或許是個不好的徵兆，好的名稱可以驅動開發、並且只需拆分與合併模組即可。

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

比如：查詢會員，可能除了查詢會員表外還要獲取該會員的其他必要資訊，但不要在查詢會員的同時還有修改許可權等類似的其他業務功能，應該分成兩個介面執行。

4. 簡單原則

介面設計簡單、清晰。API執行的功能可以很豐富、很強大，但API宣告和用法一定要儘量的簡單，不能將功能的豐富透過複雜的用法來實現，這會導致API功能不單一，演進不可控。

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

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

編寫的程式碼一定要易於讀、易於理解，這樣別人才會欣賞，也能夠給你提出合理化的建議。相反，若是繁雜難解的程式，其他人總是會避而遠之的。

5. 抽象原則

API的入參、出參所述的物件、屬性，一定是按業務特性進行抽象後的實體。誤將底層資料模型概念如實的反應到API上。抽象API、抽象物件實體更宏觀，具有更好的適用性、相容性、擴充套件性。

牛逼啊！接私活必備的 N 個開源專案！趕快收藏吧

6. 相容擴充套件原則

對擴充套件開放，對修改關閉。保證API的向後相容。

擴充套件引數應當是便利的，保證後續類似的需求，可以在已有的API上透過相容擴充套件的方式實現。

7. 最小驚訝原則

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

瞭解更多的API知識：

8. 低耦合原則

API應該減少對其他業務程式碼的依賴關係。低耦合往往是完美結構系統和優秀設計的標誌。

耦合的種類：

• 程式碼實現業務逆向呼叫。
• 條件邏輯依賴耦合。 例如：此API在處理國稅網超訂單型別時，需要額外傳送結算支付憑證上傳的事件MQ出來。
• 耦合API無關的業務行為。 例如：採購計劃鏈路日誌API被呼叫時，若是專案採購委託單的情況，需要額外呼叫公告的API拉取鏈路資訊，新建成為一條此委託單的一條鏈路日誌。

9. 正交原則

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

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

10. 易測試原則

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

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

11. 統一原則

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

統一規範的API優點：

• 易於被框架整合、處理
• 有助於API呼叫方、API提供方開發經驗複用
• 避免犯錯，避免誤用