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