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

1、 微服務(wù)API設(shè)計(jì)的實(shí)踐與思考總結(jié) 隨著微服務(wù)的越來(lái)越流行，越來(lái)的越多的公司開(kāi)始實(shí)行微服務(wù)架構(gòu)，相對(duì)于單一應(yīng)用架構(gòu)，微服務(wù)將復(fù)雜性拆分并且打散到一個(gè)個(gè)粒度更加細(xì)分的應(yīng)用中，極大了減少了開(kāi)發(fā)中單個(gè)服務(wù)的復(fù)雜性，開(kāi)發(fā)人員只需要面向?qū)Ｗ我粯I(yè)務(wù)場(chǎng)景編程，從技術(shù)開(kāi)發(fā)角度，單一服務(wù)代碼量上減少很多，從業(yè)務(wù)角度上，業(yè)務(wù)復(fù)雜性的降低降低了需求的溝通成本，然而，整體業(yè)務(wù)復(fù)雜性依然存在，當(dāng)我們需要接入或者依賴(lài)其他服務(wù)時(shí)，通常作為接入方來(lái)說(shuō)，我們不需要深入了解服務(wù)提供方的業(yè)務(wù)，此時(shí)API成為了開(kāi)發(fā)人員間的溝通語(yǔ)言。良好的API設(shè)計(jì)，能極大的減少溝通成本，甚至有時(shí)候可以代替文檔，尤其是對(duì)于基礎(chǔ)性服務(wù)來(lái)說(shuō)，服務(wù)的可擴(kuò)

2、展性有時(shí)候體現(xiàn)在API的可擴(kuò)展性，我曾經(jīng)參與過(guò)一個(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è)過(guò)程中也不斷對(duì)API設(shè)計(jì)中存在的一些問(wèn)題以及應(yīng)該遵循哪些原則進(jìn)行了一些思考。API先行在敏捷開(kāi)發(fā)的大浪潮下，產(chǎn)品上通常要求快速迭代，面對(duì)一個(gè)新的需求，如果需要開(kāi)發(fā)新的接口，通常在表結(jié)構(gòu)完成設(shè)計(jì)后，開(kāi)發(fā)人員就需要完成API設(shè)計(jì)并交付消費(fèi)方（即服務(wù)的調(diào)用方或者依賴(lài)方，文中其余部分均表示此含義），在技術(shù)聯(lián)調(diào)前，消費(fèi)方可以Mock接口來(lái)完成調(diào)試。所以通常來(lái)說(shuō)，A

3、PI先與服務(wù)交付，之后再完成編碼，測(cè)試，調(diào)試等工作。當(dāng)然，由于可能在需求細(xì)節(jié)，技術(shù)實(shí)現(xiàn)方面可能在實(shí)現(xiàn)過(guò)程中發(fā)現(xiàn)需求需要調(diào)整，或者API接口的調(diào)整，最初版本的API可能是不成熟的，導(dǎo)致我們經(jīng)常在API調(diào)整或者演化過(guò)程中在API維護(hù)方面存在很多遺漏，所以API最初交付后的維護(hù)是持續(xù)性的工作。API設(shè)計(jì)常見(jiàn)問(wèn)題在我們?cè)O(shè)計(jì)API過(guò)程中由于存在經(jīng)驗(yàn)的缺失，或者由于多次交接，或者由于經(jīng)歷多次需求的變更，導(dǎo)致服務(wù)的API慢慢腐化，帶來(lái)以下常見(jiàn)的問(wèn)題。被遺忘的注釋?zhuān)⑨屚ǔＣ枋隽薃PI的功能以及參數(shù)說(shuō)明，以及如何接入，甚至給出簡(jiǎn)單示例，過(guò)于詳細(xì)的注釋會(huì)帶來(lái)一定的反作用，例如因?yàn)樾滦枨髱?lái)了內(nèi)部邏輯的調(diào)整，但是

4、由于未及時(shí)對(duì)API的注釋進(jìn)行更新，會(huì)給新接入的調(diào)用方帶來(lái)潛在的風(fēng)險(xiǎn)。所以不僅僅需要為API提供完整清晰的注釋?zhuān)?dāng)內(nèi)部邏輯變更時(shí)，作為開(kāi)發(fā)人員通常也需要評(píng)估API層面的變更，包括注釋。接口數(shù)量持續(xù)膨脹，有很多原因帶來(lái)接口數(shù)量的膨脹，可能是接口升級(jí)，但是舊接口無(wú)法直接下線，所以會(huì)提供一個(gè)功能類(lèi)似的新接口；可能是新接管一個(gè)服務(wù)由于對(duì)業(yè)務(wù)不了解，面對(duì)新需求直接開(kāi)發(fā)新接口；可能是接口分類(lèi)劃分不合理，或者數(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ì)這類(lèi)問(wèn)題給出解決方

5、案。缺乏有效測(cè)試，很多開(kāi)發(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困擾。API設(shè)計(jì)的原則簡(jiǎn)單且專(zhuān)注簡(jiǎn)單：在面向?qū)ο笤O(shè)計(jì)原則中，第一條是單一職責(zé)原則，同樣適用于API設(shè)計(jì)，我們的主體對(duì)象就是業(yè)務(wù)模型，API就是封裝內(nèi)部邏輯后對(duì)外界開(kāi)放的功能。保證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ò)以下角度：按照業(yè)務(wù)主體劃分，不一樣

6、的業(yè)務(wù)主體采用不一樣的接口類(lèi)查詢(xún)類(lèi)和修改類(lèi)的接口分離；通常來(lái)說(shuō)我們對(duì)于數(shù)據(jù)的查詢(xún)場(chǎng)景遠(yuǎn)大于修改的場(chǎng)景，而且查詢(xún)有多種多樣的業(yè)務(wù)場(chǎng)景，對(duì)于數(shù)據(jù)的修改請(qǐng)求通常來(lái)源于業(yè)務(wù)后臺(tái)人員對(duì)數(shù)據(jù)進(jìn)行修改，此時(shí)的業(yè)務(wù)邏輯也通常會(huì)更加特殊（例如有很多額外數(shù)據(jù)校驗(yàn)），所以建議修改類(lèi)和查詢(xún)類(lèi)API盡量分離，甚至可以將業(yè)務(wù)配置后臺(tái)類(lèi)查詢(xún)和普通業(yè)務(wù)查詢(xún)分離以至于能夠適應(yīng)各自的業(yè)務(wù)變更。專(zhuān)注：一個(gè)單一接口的場(chǎng)景是基于業(yè)務(wù)抽象后專(zhuān)注于某一個(gè)場(chǎng)景并且互相不重合的，這樣才能保證接口的粒度足夠小，尤其是對(duì)于基礎(chǔ)類(lèi)服務(wù)，接口粒度的劃分能保證接口是純粹的且互相獨(dú)立的，這樣才不至于在需求變化是涉及過(guò)多接口的變動(dòng)（除非是對(duì)業(yè)務(wù)模型有較大的

7、調(diào)整），另外要說(shuō)明的是，內(nèi)部邏輯的業(yè)務(wù)數(shù)據(jù)模型（POJO類(lèi)）和API數(shù)據(jù)模型（DTO）有時(shí)候出現(xiàn)差異，否則可能需要消費(fèi)者理解服務(wù)的業(yè)務(wù)模型才能正確的使用接口，這就要求在API設(shè)計(jì)中開(kāi)發(fā)人員需要明確應(yīng)該提供哪些數(shù)據(jù)模型給消費(fèi)者，在此前提下更加有助于我們保證單一接口的專(zhuān)注。良好的注釋注釋?xiě)?yīng)該包含哪些；接口的使用場(chǎng)景，參數(shù)的說(shuō)明，在接口類(lèi)說(shuō)明中可以給出接口文檔鏈接地址，方便調(diào)用方查看參數(shù)的說(shuō)明；包含參數(shù)代表的含義，參數(shù)的類(lèi)型按照J(rèn)avadoc link規(guī)范，參數(shù)是否為空，特殊值說(shuō)明過(guò)期說(shuō)明；如果接口已經(jīng)過(guò)期，需要給出過(guò)期說(shuō)明，對(duì)于 Java 來(lái)時(shí)就是Deprecated注解，并給出切換接口說(shuō)明，如果

8、條件允許可以推動(dòng)調(diào)用方進(jìn)行接口遷移，后續(xù)對(duì)舊接口下線擴(kuò)展性唯一不變的是變化，接口也會(huì)一直演化，我們不提倡過(guò)度提前設(shè)計(jì)，但是在演化過(guò)程中要始終保持接口的可擴(kuò)展性。多參數(shù)結(jié)構(gòu)與單一參數(shù)類(lèi)結(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è)類(lèi)結(jié)構(gòu)中，記得同樣對(duì)每個(gè)字段給出完整的注釋說(shuō)明。類(lèi)復(fù)用噩夢(mèng) 在單一參數(shù)類(lèi)結(jié)構(gòu)下，我經(jīng)?？吹蕉鄠€(gè)存在明顯功能差異的接口頻繁復(fù)用一個(gè)結(jié)構(gòu)體，甚至接口參數(shù)和返回值都復(fù)用一個(gè)DTO，為了保證兼容，又不得不在同一個(gè)DTO內(nèi)不斷加字段，久而久之維護(hù)成本持續(xù)增

9、高，這是一種不合理的類(lèi)設(shè)計(jì)，如果遵守專(zhuān)注原則，這個(gè)問(wèn)題很多時(shí)候可以避免。兼容性接口邏輯或者參數(shù)變更時(shí)，需要對(duì)舊的接口保持兼容，這個(gè)是API變更時(shí)一定要遵守的原則之一，而且要通過(guò)接口測(cè)試來(lái)驗(yàn)證兼容性。是否要新增接口，當(dāng)面對(duì)一個(gè)新的需求時(shí)，為了避免對(duì)舊接口直接修改，有的開(kāi)發(fā)人員會(huì)統(tǒng)一提供新的接口，如果并非邏輯上發(fā)生較大的變更，這樣做會(huì)提高API的維護(hù)成本，后續(xù)如果不對(duì)API進(jìn)行重構(gòu)，新增加的維護(hù)成本將遠(yuǎn)大于最開(kāi)始節(jié)省的開(kāi)發(fā)成本，例如需要對(duì)某個(gè)參數(shù)增加有效校驗(yàn)，那么我們需要對(duì)兩個(gè)接口的API實(shí)現(xiàn)都做修改，而且是重復(fù)性的代碼，而且我們的影響范圍已經(jīng)成了兩個(gè)接口，這樣影響范圍的擴(kuò)大也帶來(lái)了更多的潛在風(fēng)險(xiǎn)

10、。當(dāng)然在某些場(chǎng)景例如接口邏輯出現(xiàn)大的調(diào)整，API重構(gòu)等情況下，更好的方法是提供新的接口，并推動(dòng)服務(wù)消費(fèi)者使用新的API，最后慢慢下線舊的API，這樣才能遵循簡(jiǎn)單和專(zhuān)注的原則。完善的測(cè)試單元測(cè)試，完善的單元測(cè)試能保證代碼的健壯性，提前在編碼階段發(fā)現(xiàn)并解決潛在的bug，單元測(cè)試是一個(gè)開(kāi)發(fā)人員的必備能力。接口和場(chǎng)景測(cè)試，接口測(cè)試包含內(nèi)部邏輯驗(yàn)證，異常輸入，并發(fā)等場(chǎng)景下對(duì)單一接口的驗(yàn)證，如果要對(duì)API進(jìn)行完整的邏輯驗(yàn)證，需要開(kāi)發(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ù)成本，需要開(kāi)發(fā)人員進(jìn)行利弊權(quán)衡。重視文檔良好的注釋和文檔能減少大部分和服務(wù)消費(fèi)者的溝通工作，也避免了一些錯(cuò)誤的接口調(diào)用。沒(méi)有人希望每次都需要在IM工具上浪費(fèi)大量口水或者需要當(dāng)面詢(xún)問(wèn)才知道如何正確使用API，也沒(méi)有開(kāi)發(fā)者愿意每天重復(fù)回答如何調(diào)用提供的接口。對(duì)于接口文檔，可以是采用Javadoc這樣簡(jiǎn)單的方式，也可以是通過(guò)wiki來(lái)集中管理，可以是markdown文檔，也有很多的開(kāi)源系系統(tǒng)例如Swagger，yapi，eolinker等；微服務(wù)的架構(gòu)極大的加強(qiáng)了溝通的成本，這也是