本文是《微服務(wù)治理實(shí)踐》系列篇的第四篇文章，主要分享 Spring Cloud 微服務(wù)框架下的服務(wù)契約。

在詳細(xì)講述服務(wù)契約之前，先給大家講一個(gè)場(chǎng)景。

前言

---

隨著微服務(wù)架構(gòu)越來(lái)越流行，越來(lái)越多的公司使用微服務(wù)框架進(jìn)行開發(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àng)目啦，你什么時(shí)間方便我想問(wèn)你一些問(wèn)題。這么多微服務(wù)接口，感覺不知道從哪里去看會(huì)比較好呢。

我想了想自己剛?cè)腴T時(shí)候?qū)懙睦a，還沒有注釋，無(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)題：

1. 不及時(shí)提供接口API

尤其體現(xiàn)在項(xiàng)目交接上，該問(wèn)題對(duì)人員變動(dòng)比較頻繁的組織，如高校項(xiàng)目的準(zhǔn)畢業(yè)生和新生交接、企業(yè)項(xiàng)目的外包人員交接，問(wèn)題會(huì)顯得更加突出。開發(fā)人員經(jīng)常過(guò)于關(guān)注微服務(wù)的內(nèi)部實(shí)現(xiàn)，相對(duì)較少設(shè)計(jì)API接口。

程序員最討厭的兩件事：1. 寫注釋 2. 別人不寫注釋

是不是經(jīng)常想著寫完代碼再寫注釋，但真正把代碼寫完以后，注釋/接口描述一拖再拖最后就沒有了？

2. 不及時(shí)變更接口

即使有了 API 文檔，但由于文檔的離線管理，微服務(wù)接口變更以后，文檔卻沒有及時(shí)變更，影響協(xié)作人員的開發(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)描述接口然后生成文檔不可以嗎？

可以，但剛剛我們也提到了“程序員最討厭的兩件事”，要求所有的開發(fā)人員都去主動(dòng)的按照規(guī)范寫注釋，把所有的接口、參數(shù)列表的類型、描述等信息全都寫清楚，是一件比較費(fèi)時(shí)費(fèi)力的事情。我們希望有一個(gè)能夠減少開發(fā)人員負(fù)擔(dān)的方法。

2. 現(xiàn)在不是有很多專業(yè)的 API 管理工具嗎，我直接用專業(yè)的 API 管理工具去維護(hù)也是可以的吧。

API 管理工具我們也是有考慮的，但是有如下的問(wèn)題：

• 很多工具依然缺少自動(dòng)化的API生成；
• 不是專注于解決微服務(wù)領(lǐng)域的問(wèn)題，隨著服務(wù)量迅速上升，管理起來(lái)依舊比較困難。

3. 那微服務(wù)框架本身也會(huì)有提供相關(guān)的接口管理功能吧，Dubbo可以用Dubbo Admin，Spring Cloud可以用Spring Boot Admin，它們不香嗎？

這里篇幅有限，我們不再去詳細(xì)講述開源工具我們?cè)趺慈ヒ徊讲绞褂?，詳情見表格?/span>

從表格可以看到，EDAS 3.0 微服務(wù)治理的服務(wù)契約，支持版本更廣泛了，配置難度更低了，代碼侵入性沒有了，直接用 EDAS 3.0 的 Agent 方案，它不是更香了？

EDAS 3.0 服務(wù)契約實(shí)踐

---

下面我們來(lái)體驗(yàn)一下，EDAS 3.0 上如何查看 Spring Cloud 的微服務(wù)契約。

創(chuàng)建應(yīng)用

根據(jù)你的需要，選擇集群類型和應(yīng)用運(yùn)行環(huán)境，創(chuàng)建 Provider 和 Consumer 應(yīng)用。

服務(wù)查詢控制臺(tái)

• 登錄 EDAS 3.0 控制臺(tái)，在頁(yè)面左上角選擇地域；

• 左側(cè)導(dǎo)航欄選擇：微服務(wù)治理 -> Spring Cloud / Dubbo / HSF -> 服務(wù)查詢；

• 服務(wù)查詢頁(yè)面單擊某個(gè)服務(wù)的詳情。

查看服務(wù)契約

服務(wù)詳情頁(yè)面包括基本信息、服務(wù)調(diào)用關(guān)系、接口元數(shù)據(jù)、元數(shù)據(jù)等信息。在“接口元數(shù)據(jù)”一欄，便可查看服務(wù)的API信息。當(dāng)用戶使用Swagger注解時(shí)，會(huì)在“描述”列顯示相應(yīng)信息。

服務(wù)契約實(shí)現(xiàn)細(xì)節(jié)

在設(shè)計(jì)服務(wù)契約功能的時(shí)候，我們不但解決了開源框架中配置難度大，且部分方案具有代碼侵入性的問(wèn)題，而且針對(duì)如下階段的難點(diǎn)都做了相應(yīng)的方案，相信這些地方也是微服務(wù)框架的使用者會(huì)關(guān)心的：

• 數(shù)據(jù)獲取

• 獲取的同時(shí)是否還需要其他配置？
• 如何獲取所需的方法名及描述、參數(shù)列表及描述、返回類型等信息？
• 會(huì)不會(huì)影響服務(wù)的性能？
• 信息能不能全面的拿到？
• 能不能同步接口的變更？

• 數(shù)據(jù)解析

• 能不能看到參數(shù)類型/返回值類型的詳細(xì)結(jié)構(gòu)？
• 解析參數(shù)結(jié)構(gòu)的時(shí)候會(huì)不會(huì)影響啟動(dòng)時(shí)間？
• 泛型、枚舉是否支持？
• 循環(huán)引用如何解決？

下面我們來(lái)詳細(xì)介紹一下這幾點(diǎn)都是如何解決的。

數(shù)據(jù)獲取

為了減少用戶的配置和使用難度，我們采用了 Agent 方案，用戶無(wú)需任何額外的代碼和配置，就可以使用我們的微服務(wù)治理功能。

Java Agent是一種字節(jié)碼增強(qiáng)技術(shù)，運(yùn)行時(shí)插入我們的代碼，便可穩(wěn)定的享受到所有的增強(qiáng)功能。

而且通過(guò)測(cè)試可得，只要在 SpringMVC 的映射處理階段，選取合適的攔截點(diǎn)，就可以獲取到所有的方法映射信息，包括方法名、參數(shù)列表、返回值類型、注解信息。由于該點(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ù)列表/返回值的類型是一個(gè)復(fù)雜類型，一般情況我們只看到一個(gè)類型名。那么有沒有辦法可以看到這個(gè)復(fù)雜類型的具體構(gòu)成呢？

聰明的你可能就會(huì)想到，通過(guò)反射來(lái)遞歸遍歷該類所有的 Field ，不就都解決了？思路確實(shí)如此，但實(shí)際要考慮的情況會(huì)更復(fù)雜一些。

以該復(fù)雜類型 CartItem 為例，它可能不但會(huì)包含基本類型，還可能會(huì)涉及到泛型、枚舉，以及存在循環(huán)引用的情況。

因此在解析該類型之前，我們需要先判斷一下該類型是否存在泛型、枚舉的情況，如果是，需要額外解析并存儲(chǔ)泛型列表及枚舉列表。

而循環(huán)引用問(wèn)題，我們只需借助一個(gè) typeCache 即可解決。如下圖，A和B構(gòu)成了一個(gè)循環(huán)引用。

如果我們不采取任何措施，遞歸遍歷將永遠(yuǎn)沒有出口。但是，如果我們?cè)诒闅vA的所有類型之前，先判斷一下 typeCache 里是否存在 TypeA 。對(duì) TypeB 也以此類推：

那么當(dāng)遍歷 ObjB 中所包含類型時(shí)，如果遇到了 TypeA ，同樣也會(huì)先判斷 typeCache 中是否存在。如存在，就無(wú)需再遞歸遍歷 ObjA 中所有的類型了，而是直接記錄一個(gè) A 的引用。因此，循環(huán)引用問(wèn)題也就得以解決。

最終的解析信息，可以在服務(wù)測(cè)試功能中得以體現(xiàn)。未來(lái)我們可能會(huì)支持直接在服務(wù)查詢中的服務(wù)契約頁(yè)，通過(guò)一個(gè)入口顯示復(fù)雜類型的具體解析結(jié)構(gòu)。

由此我們看到，在服務(wù)契約的獲取及解析階段，涉及到的可能影響用戶體驗(yàn)的問(wèn)題都得到了一定的解決。

作者信息：

劉旖明，花名眉生，北京郵電大學(xué)計(jì)算機(jī)學(xué)院在讀研究生，暑期作為阿里云云原生部門實(shí)習(xí)開發(fā)工程師，主要進(jìn)行阿里云微服務(wù)產(chǎn)品的相關(guān)研發(fā)，目前關(guān)注微服務(wù)、云原生等技術(shù)方向。

特別推薦一個(gè)分享架構(gòu)+算法的優(yōu)質(zhì)內(nèi)容，還沒關(guān)注的小伙伴，可以長(zhǎng)按關(guān)注一下：
長(zhǎng)按訂閱更多精彩▼
如有收獲，點(diǎn)個(gè)在看，誠(chéng)摯感謝