設(shè)計(jì)一個(gè)高質(zhì)量的 API 接口

你是否也感同身受？

• 對接XX業(yè)務(wù)時(shí)，XX業(yè)務(wù)具備的功能和API全靠跑業(yè)務(wù)負(fù)責(zé)人那反復(fù)逐個(gè)詢問、確認(rèn)。用哪個(gè)API；怎么用；有沒有限制；等等
• 各個(gè)業(yè)務(wù)間，甚至同一業(yè)務(wù)內(nèi)，API風(fēng)格不統(tǒng)一。
• API命名：?按自然語義全翻譯的；按屬性角度定義的；按操作角度定義的；動(dòng)賓、非動(dòng)賓的；復(fù)數(shù)、非復(fù)數(shù)的；等等
• API入?yún)ⅲ?/strong>?帶Map的；相同語義字段名稱不一樣；
• API出參：?有包裝Resoponse的；直接返回結(jié)果數(shù)據(jù)的；相同數(shù)據(jù)，返回格式和字段名稱有差別的；
• 錯(cuò)誤信息：?直接返回中文提示的；返回提示信息編碼的；返回異常類型的；等等
• XX業(yè)務(wù)API性能方面未知。
• 隨著業(yè)務(wù)的演進(jìn)，開放的API持續(xù)在增加，但類同的很多

API編碼規(guī)范迫在眉睫

優(yōu)秀API的特質(zhì)

自解釋

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

易學(xué)習(xí)

• 有完善的文檔，以及提供盡可能多的示例和可copy－paste的代碼。

易使用

• 功能強(qiáng)大，但使用簡單。不增加調(diào)用方的使用成本（例如要求業(yè)務(wù)方用API時(shí)需要額外的配置和依賴），不暴露復(fù)雜的細(xì)節(jié)、冗長的使用流程給調(diào)用方感知。調(diào)用方只做最小的感知和最少的傳參。

難誤用

• 優(yōu)秀的API可以使有經(jīng)驗(yàn)的開發(fā)直接使用API而不需要閱讀文檔。
• 充分的靜態(tài)檢查、動(dòng)態(tài)校驗(yàn)、顯式的異常說明、有效的錯(cuò)誤提示。

API 設(shè)計(jì)原則

1. 充分原則

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

每新建一個(gè)接口，要有充分的理由和考慮，即這個(gè)接口的存在是十分有意義和價(jià)值的。無意義的接口不僅增加了維護(hù)的難度，更重要是對于程序的可控性的大大降低，接口也會(huì)十分臃腫。

2. 單一視角原則

設(shè)計(jì)接口時(shí)，分析的角度要統(tǒng)一。否則會(huì)造成接口結(jié)構(gòu)的混亂。例如：不要一會(huì)以角色的角度設(shè)計(jì)，一會(huì)兒就要以功能的角度設(shè)計(jì)。

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

3. 單一功能原則

每個(gè)API接口應(yīng)該只專注一件事，并做好。產(chǎn)品概念簡單、關(guān)系清楚。功能模棱兩可，諸多特殊邏輯的API肯定不是個(gè)優(yōu)雅的API，且會(huì)造成功能類似重復(fù)的API。

注：如果API它很難命名，那么這或許是個(gè)不好的征兆，好的名稱可以驅(qū)動(dòng)開發(fā)、并且只需拆分與合并模塊即可。

功能大而全的API在靈活性、簡單性方面肯定捉襟見肘。定義API的粒度之前，建議先將業(yè)務(wù)分領(lǐng)域、劃邊界，以此來提取業(yè)務(wù)對象，然后再根據(jù)業(yè)務(wù)對象用例來設(shè)計(jì)單一功能的API。

比如：查詢會(huì)員，可能除了查詢會(huì)員表外還要獲取該會(huì)員的其他必要信息，但不要在查詢會(huì)員的同時(shí)還有修改權(quán)限等類似的其他業(yè)務(wù)功能，應(yīng)該分成兩個(gè)接口執(zhí)行。

4. 簡單原則

接口設(shè)計(jì)簡單、清晰。API執(zhí)行的功能可以很豐富、很強(qiáng)大，但API聲明和用法一定要盡量的簡單，不能將功能的豐富通過復(fù)雜的用法來實(shí)現(xiàn)，這會(huì)導(dǎo)致API功能不單一，演進(jìn)不可控。

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

• 你寫的例子，能不能讓你的代碼看起來更簡單？
• 你是不是強(qiáng)迫調(diào)用方關(guān)注/提供他們不在乎的選項(xiàng)/配置？
• 有沒有毫無價(jià)值的額外步驟？

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

5. 抽象原則

API的入?yún)ⅰ⒊鰠⑺龅膶ο蟆傩裕欢ㄊ前礃I(yè)務(wù)特性進(jìn)行抽象后的實(shí)體。誤將底層數(shù)據(jù)模型概念如實(shí)的反應(yīng)到API上。抽象API、抽象對象實(shí)體更宏觀，具有更好的適用性、兼容性、擴(kuò)展性。

6. 兼容擴(kuò)展原則

對擴(kuò)展開放，對修改關(guān)閉。保證API的向后兼容。

擴(kuò)展參數(shù)應(yīng)當(dāng)是便利的，保證后續(xù)類似的需求，可以在已有的API上通過兼容擴(kuò)展的方式實(shí)現(xiàn)。

7. 最小驚訝原則

代碼應(yīng)該盡可能減少讓讀者驚喜。業(yè)務(wù)API只需根據(jù)需求來設(shè)計(jì)即可，不需要刻意去設(shè)計(jì)一下復(fù)雜無用、華而不實(shí)的API，以免弄巧成拙。

8. 低耦合原則

API應(yīng)該減少對其他業(yè)務(wù)代碼的依賴關(guān)系。低耦合往往是完美結(jié)構(gòu)系統(tǒng)和優(yōu)秀設(shè)計(jì)的標(biāo)志。

耦合的種類：

• 代碼實(shí)現(xiàn)業(yè)務(wù)逆向調(diào)用。
• 條件邏輯依賴耦合。?例如：此API在處理國稅網(wǎng)超訂單類型時(shí)，需要額外發(fā)送結(jié)算支付憑證上傳的事件MQ出來。
• 耦合API無關(guān)的業(yè)務(wù)行為。?例如：采購計(jì)劃鏈路日志API被調(diào)用時(shí)，若是項(xiàng)目采購委托單的情況，需要額外調(diào)用公告的API拉取鏈路信息，新建成為一條此委托單的一條鏈路日志。

9. 正交原則

正交性是指改變某個(gè)特性而不會(huì)影響到其他的特性。

API之間的功能應(yīng)該成正交性，無功能重合。API之間應(yīng)該是互相補(bǔ)充的關(guān)系。

10. 易測試原則

對于API調(diào)用者而言，API應(yīng)該是可被測試且易于被測試的。測試API不需要依賴額外的環(huán)境、容器、配置、公共服務(wù)等。

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

11. 統(tǒng)一原則

API要具備統(tǒng)一的命名、統(tǒng)一的入/出參規(guī)范、統(tǒng)一的異常規(guī)范、統(tǒng)一的錯(cuò)誤碼規(guī)范、統(tǒng)一的版本規(guī)范等。

統(tǒng)一規(guī)范的API優(yōu)點(diǎn)：

• 易于被框架集成、處理
• 有助于API調(diào)用方、API提供方開發(fā)經(jīng)驗(yàn)復(fù)用
• 避免犯錯(cuò)，避免誤用