微服务API设计的实践与思考总结
隨著微服務(wù)的越來越流行,越來的越多的公司開始實行微服務(wù)架構(gòu),相對于單一應(yīng)用架構(gòu),微服務(wù)將復(fù)雜性拆分并且打散到一個個粒度更加細分的應(yīng)用中,極大了減少了開發(fā)中單個服務(wù)的復(fù)雜性,開發(fā)人員只需要面向?qū)W我粯I(yè)務(wù)場景編程,從技術(shù)開發(fā)角度,單一服務(wù)代碼量上減少很多,從業(yè)務(wù)角度上,業(yè)務(wù)復(fù)雜性的降低降低了需求的溝通成本,然而,整體業(yè)務(wù)復(fù)雜性依然存在,當(dāng)我們需要接入或者依賴其他服務(wù)時,通常作為接入方來說,我們不需要深入了解服務(wù)提供方的業(yè)務(wù),此時API成為了開發(fā)人員間的溝通語言。良好的API設(shè)計,能極大的減少溝通成本,甚至有時候可以代替文檔,尤其是對于基礎(chǔ)性服務(wù)來說,服務(wù)的可擴展性有時候體現(xiàn)在API的可擴展性,我曾經(jīng)參與過一個基礎(chǔ)業(yè)務(wù)微服務(wù)的業(yè)務(wù)升級,由于舊版本的API劃分不夠清晰,部分API存在重復(fù)性,后面不得不對大部分API進行重構(gòu)(替換為新版本的API),僅僅在服務(wù)消費方升級這個階段就持續(xù)1-2個月之久,在這個過程中也不斷對API設(shè)計中存在的一些問題以及應(yīng)該遵循哪些原則進行了一些思考。
API先行
在敏捷開發(fā)的大浪潮下,產(chǎn)品上通常要求快速迭代,面對一個新的需求,如果需要開發(fā)新的接口,通常在表結(jié)構(gòu)完成設(shè)計后,開發(fā)人員就需要完成API設(shè)計并交付消費方(即服務(wù)的調(diào)用方或者依賴方,文中其余部分均表示此含義),在技術(shù)聯(lián)調(diào)前,消費方可以Mock接口來完成調(diào)試。所以通常來說,API先與服務(wù)交付,之后再完成編碼,測試,調(diào)試等工作。當(dāng)然,由于可能在需求細節(jié),技術(shù)實現(xiàn)方面可能在實現(xiàn)過程中發(fā)現(xiàn)需求需要調(diào)整,或者API接口的調(diào)整,最初版本的API可能是不成熟的,導(dǎo)致我們經(jīng)常在API調(diào)整或者演化過程中在API維護方面存在很多遺漏,所以API最初交付后的維護是持續(xù)性的工作。
API設(shè)計常見問題
在我們設(shè)計API過程中由于存在經(jīng)驗的缺失,或者由于多次交接,或者由于經(jīng)歷多次需求的變更,導(dǎo)致服務(wù)的API慢慢腐化,帶來以下常見的問題。
被遺忘的注釋,注釋通常描述了API的功能以及參數(shù)說明,以及如何接入,甚至給出簡單示例,過于詳細的注釋會帶來一定的反作用,例如因為新需求帶來了內(nèi)部邏輯的調(diào)整,但是由于未及時對API的注釋進行更新,會給新接入的調(diào)用方帶來潛在的風(fēng)險。所以不僅僅需要為API提供完整清晰的注釋,當(dāng)內(nèi)部邏輯變更時,作為開發(fā)人員通常也需要評估API層面的變更,包括注釋。
接口數(shù)量持續(xù)膨脹,有很多原因帶來接口數(shù)量的膨脹,可能是接口升級,但是舊接口無法直接下線,所以會提供一個功能類似的新接口;可能是新接管一個服務(wù)由于對業(yè)務(wù)不了解,面對新需求直接開發(fā)新接口;可能是接口分類劃分不合理,或者數(shù)據(jù)模型混亂導(dǎo)致API劃分混亂,出現(xiàn)API功能重復(fù),最后導(dǎo)致一個場景多個API接口都可以滿足,這樣很明顯是應(yīng)該避免的。解決這些問題都需要建立在對業(yè)務(wù)充分理解的基礎(chǔ)上,下文的設(shè)計原則會針對這類問題給出解決方案。
缺乏有效測試,很多開發(fā)人員往往忽略對于接口的測試,無論是內(nèi)部邏輯細節(jié)的單元測試,還是接口層面的測試,都是服務(wù)健壯性的一個有效保證,如果無法對接口進行有效測試,不僅是不負責(zé)任的提現(xiàn),而且還會經(jīng)常被線上bug困擾。
API設(shè)計的原則
簡單且專注
簡單:在面向?qū)ο笤O(shè)計原則中,第一條是單一職責(zé)原則,同樣適用于API設(shè)計,我們的主體對象就是業(yè)務(wù)模型,API就是封裝內(nèi)部邏輯后對外界開放的功能。保證API的簡單和職責(zé)單一,能夠避免解決上文中提到的接口數(shù)量膨脹問題。那如何才能實現(xiàn)API職責(zé)單一,需要我們在定義接口時能夠準確識別出接口之間的關(guān)聯(lián)性和邊界,對于API如何劃分可以通過以下角度:
按照業(yè)務(wù)主體劃分,不一樣的業(yè)務(wù)主體采用不一樣的接口類
查詢類和修改類的接口分離;通常來說我們對于數(shù)據(jù)的查詢場景遠大于修改的場景,而且查詢有多種多樣的業(yè)務(wù)場景,對于數(shù)據(jù)的修改請求通常來源于業(yè)務(wù)后臺人員對數(shù)據(jù)進行修改,此時的業(yè)務(wù)邏輯也通常會更加特殊(例如有很多額外數(shù)據(jù)校驗),所以建議修改類和查詢類API盡量分離,甚至可以將業(yè)務(wù)配置后臺類查詢和普通業(yè)務(wù)查詢分離以至于能夠適應(yīng)各自的業(yè)務(wù)變更。
專注:一個單一接口的場景是基于業(yè)務(wù)抽象后專注于某一個場景并且互相不重合的,這樣才能保證接口的粒度足夠小,尤其是對于基礎(chǔ)類服務(wù),接口粒度的劃分能保證接口是純粹的且互相獨立的,這樣才不至于在需求變化是涉及過多接口的變動(除非是對業(yè)務(wù)模型有較大的調(diào)整),另外要說明的是,內(nèi)部邏輯的業(yè)務(wù)數(shù)據(jù)模型(POJO類)和API數(shù)據(jù)模型(DTO)有時候出現(xiàn)差異,否則可能需要消費者理解服務(wù)的業(yè)務(wù)模型才能正確的使用接口,這就要求在API設(shè)計中開發(fā)人員需要明確應(yīng)該提供哪些數(shù)據(jù)模型給消費者,在此前提下更加有助于我們保證單一接口的專注。
良好的注釋
注釋應(yīng)該包含哪些;接口的使用場景,參數(shù)的說明,在接口類說明中可以給出接口文檔鏈接地址,方便調(diào)用方查看
參數(shù)的說明;包含參數(shù)代表的含義,參數(shù)的類型按照Javadoc link規(guī)范,參數(shù)是否為空,特殊值說明
過期說明;如果接口已經(jīng)過期,需要給出過期說明,對于 Java 來時就是@Deprecated注解,并給出切換接口說明,如果條件允許可以推動調(diào)用方進行接口遷移,后續(xù)對舊接口下線
擴展性
唯一不變的是變化,接口也會一直演化,我們不提倡過度提前設(shè)計,但是在演化過程中要始終保持接口的可擴展性。
多參數(shù)結(jié)構(gòu)與單一參數(shù)類結(jié)構(gòu) 通常來說,如果一個接口的參數(shù)小于三個,那么建議使用多參數(shù)接口,這樣做到直觀簡潔 如果一個接口的參數(shù)較多而且后續(xù)可能經(jīng)常出現(xiàn)變動,為了便于擴展和兼容,會將參數(shù)封裝到一個類結(jié)構(gòu)中,記得同樣對每個字段給出完整的注釋說明。
類復(fù)用噩夢 在單一參數(shù)類結(jié)構(gòu)下,我經(jīng)??吹蕉鄠€存在明顯功能差異的接口頻繁復(fù)用一個結(jié)構(gòu)體,甚至接口參數(shù)和返回值都復(fù)用一個DTO,為了保證兼容,又不得不在同一個DTO內(nèi)不斷加字段,久而久之維護成本持續(xù)增高,這是一種不合理的類設(shè)計,如果遵守專注原則,這個問題很多時候可以避免。
兼容性
接口邏輯或者參數(shù)變更時,需要對舊的接口保持兼容,這個是API變更時一定要遵守的原則之一,而且要通過接口測試來驗證兼容性。
是否要新增接口,當(dāng)面對一個新的需求時,為了避免對舊接口直接修改,有的開發(fā)人員會統(tǒng)一提供新的接口,如果并非邏輯上發(fā)生較大的變更,這樣做會提高API的維護成本,后續(xù)如果不對API進行重構(gòu),新增加的維護成本將遠大于最開始節(jié)省的開發(fā)成本,例如需要對某個參數(shù)增加有效校驗,那么我們需要對兩個接口的API實現(xiàn)都做修改,而且是重復(fù)性的代碼,而且我們的影響范圍已經(jīng)成了兩個接口,這樣影響范圍的擴大也帶來了更多的潛在風(fēng)險。當(dāng)然在某些場景例如接口邏輯出現(xiàn)大的調(diào)整,API重構(gòu)等情況下,更好的方法是提供新的接口,并推動服務(wù)消費者使用新的API,最后慢慢下線舊的API,這樣才能遵循簡單和專注的原則。
完善的測試
單元測試,完善的單元測試能保證代碼的健壯性,提前在編碼階段發(fā)現(xiàn)并解決潛在的bug,單元測試是一個開發(fā)人員的必備能力。
接口和場景測試,接口測試包含內(nèi)部邏輯驗證,異常輸入,并發(fā)等場景下對單一接口的驗證,如果要對API進行完整的邏輯驗證,需要開發(fā)人員構(gòu)造完整的測試數(shù)據(jù)(通常包含scheme.sql和data.sql文件),尤其是對于基礎(chǔ)服務(wù),需要對某些復(fù)雜業(yè)務(wù)場景下聯(lián)合多個接口完成某個場景的測試,并對中間的數(shù)據(jù)和輸出進行Assert確認,這樣也會代碼一定的測試代碼維護成本,需要開發(fā)人員進行利弊權(quán)衡。
重視文檔
良好的注釋和文檔能減少大部分和服務(wù)消費者的溝通工作,也避免了一些錯誤的接口調(diào)用。沒有人希望每次都需要在IM工具上浪費大量口水或者需要當(dāng)面詢問才知道如何正確使用API,也沒有開發(fā)者愿意每天重復(fù)回答如何調(diào)用提供的接口。對于接口文檔,可以是采用Javadoc這樣簡單的方式,也可以是通過wiki來集中管理,可以是markdown文檔,也有很多的開源系系統(tǒng)例如Swagger,yapi,eolinker等;微服務(wù)的架構(gòu)極大的加強了溝通的成本,這也是微服務(wù)架構(gòu)的一個弊端,但是合理的利用 工具 可以減少不必要的溝通。
總結(jié)
作為微服務(wù)之間的橋梁,API設(shè)計和維護是微服務(wù)架構(gòu)中很重要的一個環(huán)節(jié),每個開發(fā)人員不僅僅需要良好的代碼規(guī)范,也需要建立并遵守API設(shè)計規(guī)范。API設(shè)計能力在微服務(wù)架構(gòu)中作為軟實力的一個部分,需要開發(fā)人員有一定的設(shè)計經(jīng)驗的積累,同時,只有不斷的思考和總結(jié)才能更加深入的理解。
想知道更多?掃描下面的二維碼關(guān)注我后臺回復(fù)"技術(shù)",加入技術(shù)群后臺回復(fù)“k8s”,可領(lǐng)取k8s資料【精彩推薦】原創(chuàng)|OpenAPI標準規(guī)范
中臺不是萬能藥,關(guān)于中臺的思考和嘗試
ClickHouse到底是什么?為什么如此牛逼!
原來ElasticSearch還可以這么理解
面試官:InnoDB中一棵B+樹可以存放多少行數(shù)據(jù)?
微服務(wù)下如何解耦?對于已經(jīng)緊耦合下如何重構(gòu)?
如何構(gòu)建一套高性能、高可用、低成本的視頻處理系統(tǒng)?
架構(gòu)之道:分離業(yè)務(wù)邏輯和技術(shù)細節(jié)
星巴克不使用兩階段提交
點個贊+在看,少個 bug?????
總結(jié)
以上是生活随笔為你收集整理的微服务API设计的实践与思考总结的全部內(nèi)容,希望文章能夠幫你解決所遇到的問題。
- 上一篇: 摊牌了,我 HTTP 功底贼好!
- 下一篇: Flink 还是 Spark?阿里技术专