微服務(wù) API 設(shè)計(jì)的實(shí)踐與思考總結(jié)

被遺忘的注釋，注釋通常描述了API的功能以及參數(shù)說(shuō)明，以及如何接入，甚至給出簡(jiǎn)單示例，過(guò)于詳細(xì)的注釋會(huì)帶來(lái)一定的反作用，例如因?yàn)樾滦枨髱?lái)了內(nèi)部邏輯的調(diào)整，但是由于未及時(shí)對(duì)API的注釋進(jìn)行更新，會(huì)給新接入的調(diào)用方帶來(lái)潛在的風(fēng)險(xiǎn)。所以不僅僅需要為API提供完整清晰的注釋，當(dāng)內(nèi)部邏輯變更時(shí)，作為開發(fā)人員通常也需要評(píng)估API層面的變更，包括注釋。

接口數(shù)量持續(xù)膨脹，有很多原因帶來(lái)接口數(shù)量的膨脹，可能是接口升級(jí)，但是舊接口無(wú)法直接下線，所以會(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)該避免的。解決這些問(wèn)題都需要建立在對(duì)業(yè)務(wù)充分理解的基礎(chǔ)上，下文的設(shè)計(jì)原則會(huì)針對(duì)這類問(wèn)題給出解決方案。

缺乏有效測(cè)試，很多開發(fā)人員往往忽略對(duì)于接口的測(cè)試，無(wú)論是內(nèi)部邏輯細(xì)節(jié)的單元測(cè)試，還是接口層面的測(cè)試，都是服務(wù)健壯性的一個(gè)有效保證，如果無(wú)法對(duì)接口進(jìn)行有效測(cè)試，不僅是不負(fù)責(zé)任的提現(xiàn)，而且還會(huì)經(jīng)常被線上bug困擾。

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

專注：一個(gè)單一接口的場(chǎng)景是基于業(yè)務(wù)抽象后專注于某一個(gè)場(chǎng)景并且互相不重合的，這樣才能保證接口的粒度足夠小，尤其是對(duì)于基礎(chǔ)類服務(wù)，接口粒度的劃分能保證接口是純粹的且互相獨(dú)立的，這樣才不至于在需求變化是涉及過(guò)多接口的變動(dòng)（除非是對(duì)業(yè)務(wù)模型有較大的調(diào)整），另外要說(shuō)明的是，內(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ù)的說(shuō)明，在接口類說(shuō)明中可以給出接口文檔鏈接地址，方便調(diào)用方查看

參數(shù)的說(shuō)明；包含參數(shù)代表的含義，參數(shù)的類型按照J(rèn)avadoc link規(guī)范，參數(shù)是否為空，特殊值說(shuō)明

過(guò)期說(shuō)明；如果接口已經(jīng)過(guò)期，需要給出過(guò)期說(shuō)明，對(duì)于 Java 來(lái)時(shí)就是@Deprecated注解，并給出切換接口說(shuō)明，如果條件允許可以推動(dòng)調(diào)用方進(jìn)行接口遷移，后續(xù)對(duì)舊接口下線

多參數(shù)結(jié)構(gòu)與單一參數(shù)類結(jié)構(gòu) 通常來(lái)說(shuō)，如果一個(gè)接口的參數(shù)小于三個(gè)，那么建議使用多參數(shù)接口，這樣做到直觀簡(jiǎn)潔 如果一個(gè)接口的參數(shù)較多而且后續(xù)可能經(jīng)常出現(xiàn)變動(dòng)，為了便于擴(kuò)展和兼容，會(huì)將參數(shù)封裝到一個(gè)類結(jié)構(gòu)中，記得同樣對(duì)每個(gè)字段給出完整的注釋說(shuō)明。

類復(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è)問(wèn)題很多時(shí)候可以避免。

接口邏輯或者參數(shù)變更時(shí)，需要對(duì)舊的接口保持兼容，這個(gè)是API變更時(shí)一定要遵守的原則之一，而且要通過(guò)接口測(cè)試來(lái)驗(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ò)大也帶來(lái)了更多的潛在風(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è)試能保證代碼的健壯性，提前在編碼階段發(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)衡。