[[416245]]

• API先行
• API設(shè)計(jì)常見問題
• API設(shè)計(jì)的原則
• 簡(jiǎn)單且專注
• 良好的注釋
• 擴(kuò)展性
• 兼容性
• 完善的測(cè)試
• 重視文檔
• 總結(jié)

隨著微服務(wù)的越來越流行，越來的越多的公司開始實(shí)行微服務(wù)架構(gòu)，相對(duì)于單一應(yīng)用架構(gòu)，微服務(wù)將復(fù)雜性拆分并且打散到一個(gè)個(gè)粒度更加細(xì)分的應(yīng)用中，極大了減少了開發(fā)中單個(gè)服務(wù)的復(fù)雜性，開發(fā)人員只需要面向?qū)Ｗ我粯I(yè)務(wù)場(chǎng)景編程，從技術(shù)開發(fā)角度，單一服務(wù)代碼量上減少很多，從業(yè)務(wù)角度上，業(yè)務(wù)復(fù)雜性的降低降低了需求的溝通成本，然而，整體業(yè)務(wù)復(fù)雜性依然存在，當(dāng)我們需要接入或者依賴其他服務(wù)時(shí)，通常作為接入方來說，我們不需要深入了解服務(wù)提供方的業(yè)務(wù)，此時(shí)API成為了開發(fā)人員間的溝通語言。

良好的API設(shè)計(jì)，能極大的減少溝通成本，甚至有時(shí)候可以代替文檔，尤其是對(duì)于基礎(chǔ)性服務(wù)來說，服務(wù)的可擴(kuò)展性有時(shí)候體現(xiàn)在API的可擴(kuò)展性，我曾經(jīng)參與過一個(gè)基礎(chǔ)業(yè)務(wù)微服務(wù)的業(yè)務(wù)升級(jí)，由于舊版本的API劃分不夠清晰，部分API存在重復(fù)性，后面不得不對(duì)大部分API進(jìn)行重構(gòu)（替換為新版本的API），僅僅在服務(wù)消費(fèi)方升級(jí)這個(gè)階段就持續(xù)1-2個(gè)月之久，在這個(gè)過程中也不斷對(duì)API設(shè)計(jì)中存在的一些問題以及應(yīng)該遵循哪些原則進(jìn)行了一些思考。

API先行

在敏捷開發(fā)的大浪潮下，產(chǎn)品上通常要求快速迭代，面對(duì)一個(gè)新的需求，如果需要開發(fā)新的接口，通常在表結(jié)構(gòu)完成設(shè)計(jì)后，開發(fā)人員就需要完成API設(shè)計(jì)并交付消費(fèi)方（即服務(wù)的調(diào)用方或者依賴方，文中其余部分均表示此含義），在技術(shù)聯(lián)調(diào)前，消費(fèi)方可以Mock接口來完成調(diào)試。所以通常來說，API先與服務(wù)交付，之后再完成編碼，測(cè)試，調(diào)試等工作。

當(dāng)然，由于可能在需求細(xì)節(jié)，技術(shù)實(shí)現(xiàn)方面可能在實(shí)現(xiàn)過程中發(fā)現(xiàn)需求需要調(diào)整，或者API接口的調(diào)整，最初版本的API可能是不成熟的，導(dǎo)致我們經(jīng)常在API調(diào)整或者演化過程中在API維護(hù)方面存在很多遺漏，所以API最初交付后的維護(hù)是持續(xù)性的工作。

API設(shè)計(jì)常見問題

在我們?cè)O(shè)計(jì)API過程中由于存在經(jīng)驗(yàn)的缺失，或者由于多次交接，或者由于經(jīng)歷多次需求的變更，導(dǎo)致服務(wù)的API慢慢腐化，帶來以下常見的問題。

• 被遺忘的注釋，注釋通常描述了API的功能以及參數(shù)說明，以及如何接入，甚至給出簡(jiǎn)單示例，過于詳細(xì)的注釋會(huì)帶來一定的反作用，例如因?yàn)樾滦枨髱砹藘?nèi)部邏輯的調(diào)整，但是由于未及時(shí)對(duì)API的注釋進(jìn)行更新，會(huì)給新接入的調(diào)用方帶來潛在的風(fēng)險(xiǎn)。所以不僅僅需要為API提供完整清晰的注釋，當(dāng)內(nèi)部邏輯變更時(shí)，作為開發(fā)人員通常也需要評(píng)估API層面的變更，包括注釋。
• 接口數(shù)量持續(xù)膨脹，有很多原因帶來接口數(shù)量的膨脹，可能是接口升級(jí)，但是舊接口無法直接下線，所以會(huì)提供一個(gè)功能類似的新接口；可能是新接管一個(gè)服務(wù)由于對(duì)業(yè)務(wù)不了解，面對(duì)新需求直接開發(fā)新接口；可能是接口分類劃分不合理，或者數(shù)據(jù)模型混亂導(dǎo)致API劃分混亂，出現(xiàn)API功能重復(fù)，最后導(dǎo)致一個(gè)場(chǎng)景多個(gè)API接口都可以滿足，這樣很明顯是應(yīng)該避免的。解決這些問題都需要建立在對(duì)業(yè)務(wù)充分理解的基礎(chǔ)上，下文的設(shè)計(jì)原則會(huì)針對(duì)這類問題給出解決方案。
• 缺乏有效測(cè)試，很多開發(fā)人員往往忽略對(duì)于接口的測(cè)試，無論是內(nèi)部邏輯細(xì)節(jié)的單元測(cè)試，還是接口層面的測(cè)試，都是服務(wù)健壯性的一個(gè)有效保證，如果無法對(duì)接口進(jìn)行有效測(cè)試，不僅是不負(fù)責(zé)任的提現(xiàn)，而且還會(huì)經(jīng)常被線上bug困擾。

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

簡(jiǎn)單且專注

• 簡(jiǎn)單：在面向?qū)ο笤O(shè)計(jì)原則中，第一條是單一職責(zé)原則，同樣適用于API設(shè)計(jì)，我們的主體對(duì)象就是業(yè)務(wù)模型，API就是封裝內(nèi)部邏輯后對(duì)外界開放的功能。保證API的簡(jiǎn)單和職責(zé)單一，能夠避免解決上文中提到的接口數(shù)量膨脹問題。那如何才能實(shí)現(xiàn)API職責(zé)單一，需要我們?cè)诙x接口時(shí)能夠準(zhǔn)確識(shí)別出接口之間的關(guān)聯(lián)性和邊界，對(duì)于API如何劃分可以通過以下角度：

  • 按照業(yè)務(wù)主體劃分，不一樣的業(yè)務(wù)主體采用不一樣的接口類
  • 查詢類和修改類的接口分離；通常來說我們對(duì)于數(shù)據(jù)的查詢場(chǎng)景遠(yuǎn)大于修改的場(chǎng)景，而且查詢有多種多樣的業(yè)務(wù)場(chǎng)景，對(duì)于數(shù)據(jù)的修改請(qǐng)求通常來源于業(yè)務(wù)后臺(tái)人員對(duì)數(shù)據(jù)進(jìn)行修改，此時(shí)的業(yè)務(wù)邏輯也通常會(huì)更加特殊（例如有很多額外數(shù)據(jù)校驗(yàn)），所以建議修改類和查詢類API盡量分離，甚至可以將業(yè)務(wù)配置后臺(tái)類查詢和普通業(yè)務(wù)查詢分離以至于能夠適應(yīng)各自的業(yè)務(wù)變更。

• 專注：一個(gè)單一接口的場(chǎng)景是基于業(yè)務(wù)抽象后專注于某一個(gè)場(chǎng)景并且互相不重合的，這樣才能保證接口的粒度足夠小，尤其是對(duì)于基礎(chǔ)類服務(wù)，接口粒度的劃分能保證接口是純粹的且互相獨(dú)立的，這樣才不至于在需求變化是涉及過多接口的變動(dòng)（除非是對(duì)業(yè)務(wù)模型有較大的調(diào)整），另外要說明的是，內(nèi)部邏輯的業(yè)務(wù)數(shù)據(jù)模型（POJO類）和API數(shù)據(jù)模型（DTO）有時(shí)候出現(xiàn)差異，否則可能需要消費(fèi)者理解服務(wù)的業(yè)務(wù)模型才能正確的使用接口，這就要求在API設(shè)計(jì)中開發(fā)人員需要明確應(yīng)該提供哪些數(shù)據(jù)模型給消費(fèi)者，在此前提下更加有助于我們保證單一接口的專注。

良好的注釋

• 注釋應(yīng)該包含哪些；接口的使用場(chǎng)景，參數(shù)的說明，在接口類說明中可以給出接口文檔鏈接地址，方便調(diào)用方查看
• 參數(shù)的說明；包含參數(shù)代表的含義，參數(shù)的類型按照J(rèn)avadoc link規(guī)范，參數(shù)是否為空，特殊值說明
• 過期說明；如果接口已經(jīng)過期，需要給出過期說明，對(duì)于 Java 來時(shí)就是@Deprecated注解，并給出切換接口說明，如果條件允許可以推動(dòng)調(diào)用方進(jìn)行接口遷移，后續(xù)對(duì)舊接口下線

擴(kuò)展性

唯一不變的是變化，接口也會(huì)一直演化，我們不提倡過度提前設(shè)計(jì)，但是在演化過程中要始終保持接口的可擴(kuò)展性。

• 多參數(shù)結(jié)構(gòu)與單一參數(shù)類結(jié)構(gòu) 通常來說，如果一個(gè)接口的參數(shù)小于三個(gè)，那么建議使用多參數(shù)接口，這樣做到直觀簡(jiǎn)潔 如果一個(gè)接口的參數(shù)較多而且后續(xù)可能經(jīng)常出現(xiàn)變動(dòng)，為了便于擴(kuò)展和兼容，會(huì)將參數(shù)封裝到一個(gè)類結(jié)構(gòu)中，記得同樣對(duì)每個(gè)字段給出完整的注釋說明。
• 類復(fù)用噩夢(mèng) 在單一參數(shù)類結(jié)構(gòu)下，我經(jīng)?？吹蕉鄠€(gè)存在明顯功能差異的接口頻繁復(fù)用一個(gè)結(jié)構(gòu)體，甚至接口參數(shù)和返回值都復(fù)用一個(gè)DTO，為了保證兼容，又不得不在同一個(gè)DTO內(nèi)不斷加字段，久而久之維護(hù)成本持續(xù)增高，這是一種不合理的類設(shè)計(jì)，如果遵守專注原則，這個(gè)問題很多時(shí)候可以避免。

兼容性

• 接口邏輯或者參數(shù)變更時(shí)，需要對(duì)舊的接口保持兼容，這個(gè)是API變更時(shí)一定要遵守的原則之一，而且要通過接口測(cè)試來驗(yàn)證兼容性。
• 是否要新增接口，當(dāng)面對(duì)一個(gè)新的需求時(shí)，為了避免對(duì)舊接口直接修改，有的開發(fā)人員會(huì)統(tǒng)一提供新的接口，如果并非邏輯上發(fā)生較大的變更，這樣做會(huì)提高API的維護(hù)成本，后續(xù)如果不對(duì)API進(jìn)行重構(gòu)，新增加的維護(hù)成本將遠(yuǎn)大于最開始節(jié)省的開發(fā)成本，例如需要對(duì)某個(gè)參數(shù)增加有效校驗(yàn)，那么我們需要對(duì)兩個(gè)接口的API實(shí)現(xiàn)都做修改，而且是重復(fù)性的代碼，而且我們的影響范圍已經(jīng)成了兩個(gè)接口，這樣影響范圍的擴(kuò)大也帶來了更多的潛在風(fēng)險(xiǎn)。當(dāng)然在某些場(chǎng)景例如接口邏輯出現(xiàn)大的調(diào)整，API重構(gòu)等情況下，更好的方法是提供新的接口，并推動(dòng)服務(wù)消費(fèi)者使用新的API，最后慢慢下線舊的API，這樣才能遵循簡(jiǎn)單和專注的原則。

完善的測(cè)試

• 單元測(cè)試，完善的單元測(cè)試能保證代碼的健壯性，提前在編碼階段發(fā)現(xiàn)并解決潛在的bug，單元測(cè)試是一個(gè)開發(fā)人員的必備能力。
• 接口和場(chǎng)景測(cè)試，接口測(cè)試包含內(nèi)部邏輯驗(yàn)證，異常輸入，并發(fā)等場(chǎng)景下對(duì)單一接口的驗(yàn)證，如果要對(duì)API進(jìn)行完整的邏輯驗(yàn)證，需要開發(fā)人員構(gòu)造完整的測(cè)試數(shù)據(jù)（通常包含scheme.sql和data.sql文件），尤其是對(duì)于基礎(chǔ)服務(wù)，需要對(duì)某些復(fù)雜業(yè)務(wù)場(chǎng)景下聯(lián)合多個(gè)接口完成某個(gè)場(chǎng)景的測(cè)試，并對(duì)中間的數(shù)據(jù)和輸出進(jìn)行Assert確認(rèn)，這樣也會(huì)代碼一定的測(cè)試代碼維護(hù)成本，需要開發(fā)人員進(jìn)行利弊權(quán)衡。

重視文檔

良好的注釋和文檔能減少大部分和服務(wù)消費(fèi)者的溝通工作，也避免了一些錯(cuò)誤的接口調(diào)使用。沒有人希望每次都需要在IM工具上浪費(fèi)大量口水或者需要當(dāng)面詢問才知道如何正確使用API，也沒有開發(fā)者愿意每天重復(fù)回答如何調(diào)用提供的接口。

對(duì)于接口文檔，可以是采用Javadoc這樣簡(jiǎn)單的方式，也可以是通過wiki來集中管理，可以是markdown文檔，也有很多的開源系系統(tǒng)例如Swagger，yapi，eolinker等；微服務(wù)的架構(gòu)極大的加強(qiáng)了溝通的成本，這也是微服務(wù)架構(gòu)的一個(gè)弊端，但是合理的利用 工具 可以減少不必要的溝通。

總結(jié)

作為微服務(wù)之間的橋梁，API設(shè)計(jì)和維護(hù)是微服務(wù)架構(gòu)中很重要的一個(gè)環(huán)節(jié)，每個(gè)開發(fā)人員不僅僅需要良好的代碼規(guī)范，也需要建立并遵守API設(shè)計(jì)規(guī)范。API設(shè)計(jì)能力在微服務(wù)架構(gòu)中作為軟實(shí)力的一個(gè)部分，需要開發(fā)人員有一定的設(shè)計(jì)經(jīng)驗(yàn)的積累，同時(shí)，只有不斷的思考和總結(jié)才能更加深入的理解。