1
前言

隨著微服務的越來越流行，越來的越多的公司開始實行微服務架構，相對於單一應用架構，微服務將複雜性拆分並且打散到一個個粒度更加細分的應用中，極大了減少了開發中單個服務的複雜性，開發人員只需要面向專注單一業務場景程式設計，從技術開發角度，單一服務程式碼量上減少很多，從業務角度上，業務複雜性的降低降低了需求的溝通成本，然而，整體業務複雜性依然存在，當我們需要接入或者依賴其他服務時，通常作為接入方來說，我們不需要深入瞭解服務提供方的業務，此時API成為了開發人員間的溝通語言。良好的API設計，能極大的減少溝通成本，甚至有時候可以代替文件，尤其是對於基礎性服務來說，服務的可擴充套件性有時候體現在API的可擴充套件性，我曾經參與過一個基礎業務微服務的業務升級，由於舊版本的API劃分不夠清晰，部分API存在重複性，後面不得不對大部分API進行重構（替換為新版本的API），僅僅在服務消費方升級這個階段就持續1-2個月之久，在這個過程中也不斷對API設計中存在的一些問題以及應該遵循哪些原則進行了一些思考。
2
API先行

在敏捷開發的大浪潮下，產品上通常要求快速迭代，面對一個新的需求，如果需要開發新的介面，通常在表結構完成設計後，開發人員就需要完成API設計並交付消費方（即服務的呼叫方或者依賴方，文中其餘部分均表示此含義），在技術聯調前，消費方可以Mock介面來完成除錯。所以通常來說，API先與服務交付，之後再完成編碼，測試，除錯等工作。當然，由於可能在需求細節，技術實現方面可能在實現過程中發現需求需要調整，或者API介面的調整，最初版本的API可能是不成熟的，導致我們經常在API調整或者演化過程中在API維護方面存在很多遺漏，所以API最初交付後的維護是持續性的工作。
3
API設計常見問題

在我們設計API過程中由於存在經驗的缺失，或者由於多次交接，或者由於經歷多次需求的變更，導致服務的API慢慢腐化，帶來以下常見的問題。被遺忘的註釋
註釋通常描述了API的功能以及引數說明，以及如何接入，甚至給出簡單示例，過於詳細的註釋會帶來一定的反作用，例如因為新需求帶來了內部邏輯的調整，但是由於未及時對API的註釋進行更新，會給新接入的呼叫方帶來潛在的風險。所以不僅僅需要為API提供完整清晰的註釋，當內部邏輯變更時，作為開發人員通常也需要評估API層面的變更，包括註釋。
介面數量持續膨脹
有很多原因帶來介面數量的膨脹，可能是介面升級，但是舊介面無法直接下線，所以會提供一個功能類似的新介面；可能是新接管一個服務由於對業務不瞭解，面對新需求直接開發新介面；可能是介面分類劃分不合理，或者資料模型混亂導致API劃分混亂，出現API功能重複，最後導致一個場景多個API介面都可以滿足，這樣很明顯是應該避免的。解決這些問題都需要建立在對業務充分理解的基礎上，下文的設計原則會針對這類問題給出解決方案。

缺乏有效測試
很多開發人員往往忽略對於介面的測試，無論是內部邏輯細節的單元測試，還是介面層面的測試，都是服務健壯性的一個有效保證，如果無法對介面進行有效測試，不僅是不負責任的提現，而且還會經常被線上bug困擾。
4
API設計的原則

1. 簡單且專注在面向物件設計原則中，第一條是單一職責原則，同樣適用於API設計，我們的主體物件就是業務模型，API就是封裝內部邏輯後對外界開放的功能。保證API的簡單和職責單一，能夠避免解決上文中提到的介面數量膨脹問題。那如何才能實現API職責單一，需要我們在定義介面時能夠準確識別出介面之間的關聯性和邊界，對於API如何劃分可以通過以下角度  1. 按照業務主體劃分，不一樣的業務主體採用不一樣的介面類  2. 查詢類和修改類的介面分離；通常來說我們對於資料的查詢場景遠大於修改的場景，而且查詢有多種多樣的業務場景，對於資料的修改請求通常來源於業務後臺人員對資料進行修改，此時的業務邏輯也通常會更加特殊（例如有很多額外資料校驗），所以建議修改類和查詢類API儘量分離，甚至可以將業務配置後臺類查詢和普通業務查詢分離以至於能夠適應各自的業務變更。一個單一介面的場景是基於業務抽象後專注於某一個場景並且互相不重合的，這樣才能保證介面的粒度足夠小，尤其是對於基礎類服務，介面粒度的劃分能保證介面是純粹的且互相獨立的，這樣才不至於在需求變化是涉及過多介面的變動（除非是對業務模型有較大的調整），另外要說明的是，內部邏輯的業務資料模型（POJO類）和API資料模型（DTO）有時候出現差異，否則可能需要消費者理解服務的業務模型才能正確的使用介面，這就要求在API設計中開發人員需要明確應該提供哪些資料模型給消費者，在此前提下更加有助於我們保證單一介面的專注。2. 良好的註釋註釋應該包含哪些；
介面的使用場景，引數的說明，在介面類說明中可以給出介面文件連結地址，方便呼叫方檢視
引數的說明；
包含引數代表的含義，引數的型別按照Javadoc link