本文是《微服務(wù)治理實(shí)踐》系列篇的第四篇文章，主要分享 Spring Cloud 微服務(wù)框架下的服務(wù)契約。
在詳細(xì)講述服務(wù)契約之前，先給大家講一個(gè)場(chǎng)景。
前言
隨著微服務(wù)架構(gòu)越來(lái)越流行，越來(lái)越多的公司使用微服務(wù)框架進(jìn)行開(kāi)發(fā)。甚至不止是公司，連筆者的研究生導(dǎo)師都要對(duì)實(shí)驗(yàn)室的 Spring Boot 工程項(xiàng)目轉(zhuǎn)型使用微服務(wù)框架了。隨著時(shí)間的推移，服務(wù)量逐漸上升，小學(xué)妹吃不消跑來(lái)問(wèn)我問(wèn)題：
一姐，我來(lái)交接你之前寫(xiě)的項(xiàng)目啦，你什么時(shí)間方便我想問(wèn)你一些問(wèn)題。這么多微服務(wù)接口，感覺(jué)不知道從哪里去看會(huì)比較好呢。
我想了想自己剛?cè)腴T(mén)時(shí)候?qū)懙睦a，還沒(méi)有注釋?zhuān)瑹o(wú)語(yǔ)凝噎。
好。我平時(shí)工作日在實(shí)習(xí)，周末給你講哈。
于是到周末，花了整整一個(gè)晚上的時(shí)間，終于給零基礎(chǔ)學(xué)妹從眾多接口的含義，到參數(shù)列表的解析，最后到講解百度應(yīng)該搜什么關(guān)鍵詞，全方位視頻指導(dǎo)。學(xué)妹十分感動(dòng)：
一姐你太貼心了555，跟別人協(xié)作項(xiàng)目的時(shí)候，經(jīng)常能講上幾句就不錯(cuò)了，然后我還是什么都不明白，改完接口也不及時(shí)告訴我。還是你最好了，后面還有什么不懂的我再來(lái)問(wèn)你哦。
從以上場(chǎng)景，我們可以總結(jié)出使用微服務(wù)框架后，會(huì)帶來(lái)的幾點(diǎn)進(jìn)度協(xié)同問(wèn)題：
尤其體現(xiàn)在項(xiàng)目交接上，該問(wèn)題對(duì)人員變動(dòng)比較頻繁的組織，如高校項(xiàng)目的準(zhǔn)畢業(yè)生和新生交接、企業(yè)項(xiàng)目的外包人員交接，問(wèn)題會(huì)顯得更加突出。開(kāi)發(fā)人員經(jīng)常過(guò)于關(guān)注微服務(wù)的內(nèi)部實(shí)現(xiàn)，相對(duì)較少設(shè)計(jì)API接口。
程序員最討厭的兩件事：1. 寫(xiě)注釋 2. 別人不寫(xiě)注釋
是不是經(jīng)常想著寫(xiě)完代碼再寫(xiě)注釋?zhuān)嬲汛a寫(xiě)完以后，注釋/接口描述一拖再拖最后就沒(méi)有了？
即使有了 API 文檔，但由于文檔的離線(xiàn)管理，微服務(wù)接口變更以后，文檔卻沒(méi)有及時(shí)變更，影響協(xié)作人員的開(kāi)發(fā)進(jìn)度。
綜上我們看到，我們不但希望所有的微服務(wù)接口都可以很方便的添加規(guī)范的接口描述，而且也能隨著接口的變更及時(shí)更新文檔。因此，我們需要服務(wù)契約來(lái)幫助我們解決這些問(wèn)題。
為什么我們需要服務(wù)契約
首先我們來(lái)看服務(wù)契約的定義：
服務(wù)契約指基于 OpenAPI 規(guī)范的微服務(wù)接口描述，是微服務(wù)系統(tǒng)運(yùn)行和治理的基礎(chǔ)。
有人可能會(huì)問(wèn)了，既然想要規(guī)范的描述接口，我有很多其他的方式啊，為什么我要用服務(wù)契約？
1. 我用 Javadoc 來(lái)描述接口然后生成文檔不可以嗎？
可以，但剛剛我們也提到了“程序員最討厭的兩件事”，要求所有的開(kāi)發(fā)人員都去主動(dòng)的按照規(guī)范寫(xiě)注釋?zhuān)阉械慕涌凇?shù)列表的類(lèi)型、描述等信息全都寫(xiě)清楚，是一件比較費(fèi)時(shí)費(fèi)力的事情。我們希望有一個(gè)能夠減少開(kāi)發(fā)人員負(fù)擔(dān)的方法。
2. 現(xiàn)在不是有很多專(zhuān)業(yè)的 API 管理工具嗎，我直接用專(zhuān)業(yè)的 API 管理工具去維護(hù)也是可以的吧。
API 管理工具我們也是有考慮的，但是有如下的問(wèn)題：
-
-
不是專(zhuān)注于解決微服務(wù)領(lǐng)域的問(wèn)題，隨著服務(wù)量迅速上升，管理起來(lái)依舊比較困難。
3. 那微服務(wù)框架本身也會(huì)有提供相關(guān)的接口管理功能吧，Dubbo可以用Dubbo Admin，Spring Cloud可以用Spring Boot Admin，它們不香嗎？
這里篇幅有限，我們不再去詳細(xì)講述開(kāi)源工具我們?cè)趺慈ヒ徊讲绞褂?，詳情?jiàn)表格：
從表格可以看到，EDAS 3.0 微服務(wù)治理的服務(wù)契約，支持版本更廣泛了，配置難度更低了，代碼侵入性沒(méi)有了，直接用 EDAS 3.0 的 Agent 方案，它不是更香了？
EDAS 3.0 服務(wù)契約實(shí)踐
下面我們來(lái)體驗(yàn)一下，EDAS 3.0 上如何查看 Spring Cloud 的微服務(wù)契約。
創(chuàng)建應(yīng)用
根據(jù)你的需要，選擇集群類(lèi)型和應(yīng)用運(yùn)行環(huán)境，創(chuàng)建 Provider 和 Consumer 應(yīng)用。
服務(wù)查詢(xún)控制臺(tái)
登錄 EDAS 3.0 控制臺(tái)，在頁(yè)面左上角選擇地域；
左側(cè)導(dǎo)航欄選擇：微服務(wù)治理 -> Spring Cloud / Dubbo / HSF -> 服務(wù)查詢(xún)；
服務(wù)查詢(xún)頁(yè)面單擊某個(gè)服務(wù)的詳情。
查看服務(wù)契約
服務(wù)詳情頁(yè)面包括基本信息、服務(wù)調(diào)用關(guān)系、接口元數(shù)據(jù)、元數(shù)據(jù)等信息。在“接口元數(shù)據(jù)”一欄，便可查看服務(wù)的API信息。當(dāng)用戶(hù)使用Swagger注解時(shí)，會(huì)在“描述”列顯示相應(yīng)信息。
服務(wù)契約實(shí)現(xiàn)細(xì)節(jié)
在設(shè)計(jì)服務(wù)契約功能的時(shí)候，我們不但解決了開(kāi)源框架中配置難度大，且部分方案具有代碼侵入性的問(wèn)題，而且針對(duì)如下階段的難點(diǎn)都做了相應(yīng)的方案，相信這些地方也是微服務(wù)框架的使用者會(huì)關(guān)心的：
-
-
如何獲取所需的方法名及描述、參數(shù)列表及描述、返回類(lèi)型等信息？
-
會(huì)不會(huì)影響服務(wù)的性能？
-
-
-
能不能看到參數(shù)類(lèi)型/返回值類(lèi)型的詳細(xì)結(jié)構(gòu)？
-
解析參數(shù)結(jié)構(gòu)的時(shí)候會(huì)不會(huì)影響啟動(dòng)時(shí)間？
-
-
下面我們來(lái)詳細(xì)介紹一下這幾點(diǎn)都是如何解決的。
數(shù)據(jù)獲取
為了減少用戶(hù)的配置和使用難度，我們采用了 Agent 方案，用戶(hù)無(wú)需任何額外的代碼和配置，就可以使用我們的微服務(wù)治理功能。
Java Agent是一種字節(jié)碼增強(qiáng)技術(shù)，運(yùn)行時(shí)插入我們的代碼，便可穩(wěn)定的享受到所有的增強(qiáng)功能。
而且通過(guò)測(cè)試可得，只要在 SpringMVC 的映射處理階段，選取合適的攔截點(diǎn)，就可以獲取到所有的方法映射信息，包括方法名、參數(shù)列表、返回值類(lèi)型、注解信息。由于該點(diǎn)在應(yīng)用啟動(dòng)過(guò)程中只發(fā)生一次，因此不會(huì)有性能的影響。
我們獲取的注解主要是針對(duì) Swagger 注解。作為 OpenAPI 規(guī)范的主要指定者， Swagger 雖并非是唯一支持 OpenAPI 的工具，但也基本屬于一種事實(shí)標(biāo)準(zhǔn)。注解解析的內(nèi)容在表格的描述部分進(jìn)行展示：
-
Swagger2的注解解析（如@ApiOperation，@ApiParam，@ApiImplicitParam），解析value值在“描述”列顯示；
-
OpenAPI3的注解解析（如@Operation，@Parameter），解析description值在“描述”列顯示。
當(dāng)接口發(fā)生變更時(shí)，只要將新版本的應(yīng)用部署上去，顯示的服務(wù)契約信息就會(huì)是最新的，無(wú)需擔(dān)心接口描述信息不能同步的問(wèn)題。
數(shù)據(jù)解析
如果參數(shù)列表/返回值的類(lèi)型是一個(gè)復(fù)雜類(lèi)型，一般情況我們只看到一個(gè)類(lèi)型名。那么有沒(méi)有辦法可以看到這個(gè)復(fù)雜類(lèi)型的具體構(gòu)成呢？
聰明的你可能就會(huì)想到，通過(guò)反射來(lái)遞歸遍歷該類(lèi)所有的 Field ，不就都解決了？思路確實(shí)如此，但實(shí)際要考慮的情況會(huì)更復(fù)雜一些。
以該復(fù)雜類(lèi)型 CartItem 為例，它可能不但會(huì)包含基本類(lèi)型，還可能會(huì)涉及到泛型、枚舉，以及存在循環(huán)引用的情況。
因此在解析該類(lèi)型之前，我們需要先判斷一下該類(lèi)型是否存在泛型、枚舉的情況，如果是，需要額外解析并存儲(chǔ)泛型列表及枚舉列表。
而循環(huán)引用問(wèn)題，我們只需借助一個(gè) typeCache 即可解決。如下圖，A和B構(gòu)成了一個(gè)循環(huán)引用。
如果我們不采取任何措施，遞歸遍歷將永遠(yuǎn)沒(méi)有出口。但是，如果我們?cè)诒闅vA的所有類(lèi)型之前，先判斷一下 typeCache 里是否存在 TypeA 。對(duì) TypeB 也以此類(lèi)推：
那么當(dāng)遍歷 ObjB 中所包含類(lèi)型時(shí)，如果遇到了 TypeA ，同樣也會(huì)先判斷 typeCache 中是否存在。如存在，就無(wú)需再遞歸遍歷 ObjA 中所有的類(lèi)型了，而是直接記錄一個(gè) A 的引用。因此，循環(huán)引用問(wèn)題也就得以解決。
最終的解析信息，可以在服務(wù)測(cè)試功能中得以體現(xiàn)。未來(lái)我們可能會(huì)支持直接在服務(wù)查詢(xún)中的服務(wù)契約頁(yè)，通過(guò)一個(gè)入口顯示復(fù)雜類(lèi)型的具體解析結(jié)構(gòu)。
由此我們看到，在服務(wù)契約的獲取及解析階段，涉及到的可能影響用戶(hù)體驗(yàn)的問(wèn)題都得到了一定的解決。
劉旖明，花名眉生，北京郵電大學(xué)計(jì)算機(jī)學(xué)院在讀研究生，暑期作為阿里云云原生部門(mén)實(shí)習(xí)開(kāi)發(fā)工程師，主要進(jìn)行阿里云微服務(wù)產(chǎn)品的相關(guān)研發(fā)，目前關(guān)注微服務(wù)、云原生等技術(shù)方向。
特別推薦一個(gè)分享架構(gòu)+算法的優(yōu)質(zhì)內(nèi)容，還沒(méi)關(guān)注的小伙伴，可以長(zhǎng)按關(guān)注一下：
長(zhǎng)按訂閱更多精彩▼
如有收獲，點(diǎn)個(gè)在看，誠(chéng)摯感謝
免責(zé)聲明：本文內(nèi)容由21ic獲得授權(quán)后發(fā)布，版權(quán)歸原作者所有，本平臺(tái)僅提供信息存儲(chǔ)服務(wù)。文章僅代表作者個(gè)人觀點(diǎn)，不代表本平臺(tái)立場(chǎng)，如有問(wèn)題，請(qǐng)聯(lián)系我們，謝謝！
下載文檔
