本文是《微服務治理實踐》系列篇的第四篇文章，主要分享Spring Cloud微服務架構下的服務契約。 第一篇：《微服務治了解密》 第二篇：《微服務治理實踐：服務查詢》 第三篇：《微服務治理實踐：金絲雀釋出》 在詳細講述服務契約之前，先給大家講一個場景。
前言
随着微服務架構越來越流行，越來越多的公司使用微服務架構進行開發。甚至不止是公司，連筆者的研究所學生導師都要對實驗室的Spring Boot工程項目轉型使用微服務架構了。随着時間的推移，服務量逐漸上升，國小妹吃不消跑來問我問題：
一姐，我來交接你之前寫的項目啦，你什麼時間友善我想問你一些問題。這麼多微服務接口，感覺不知道從哪裡去看會比較好呢。
我想了想自己剛入門時候寫的垃圾代碼，還沒有注釋，無語凝噎。
好。我平時工作日在實習，周末給你講哈。
于是到周末，花了整整一個晚上的時間，終于給零基礎學妹從衆多接口的含義，到參數清單的解析，最後到講解百度應該搜什麼關鍵詞（我好南），全方位視訊指導。學妹十分感動：
一姐你太貼心了555，跟别人協作項目的時候，經常能講上幾句就不錯了，然後我還是什麼都不明白，改完接口也不及時告訴我。還是你最好了，後面還有什麼不懂的我再來問你哦。
從以上場景，我們可以總結出使用微服務架構後，會帶來的幾點進度協同問題：
1、不及時提供接口API：
尤其展現在項目交接上，該問題對人員變動比較頻繁的組織，如高校項目的準畢業生和新生交接、企業項目的外包人員交接，問題會顯得更加突出。開發人員經常過于關注微服務的内部實作，相對較少設計API接口。
程式員最讨厭的兩件事：1. 寫注釋 2. 别人不寫注釋
是不是經常想着寫完代碼再寫注釋，但真正把代碼寫完以後，注釋/接口描述一拖再拖最後就沒有了？别告訴我你沒有過。
2、不及時變更接口：
即使有了API文檔，但由于文檔的離線管理，微服務接口變更以後，文檔卻沒有及時變更，影響協作人員的開發進度。
綜上我們看到，我們不但希望所有的微服務接口都可以很友善的添加規範的接口描述，而且也能随着接口的變更及時更新文檔。是以，我們需要服務契約來幫助我們解決這些問題。
為什麼我們需要服務契約
首先我們來看服務契約的定義：
服務契約指基于OpenAPI規範的微服務接口描述，是微服務系統運作和治理的基礎。
有人可能會問了，既然想要規範的描述接口，我有很多其他的方式啊，為什麼我要用服務契約？
1、 我用Javadoc來描述接口然後生成文檔不可以嗎？
可以，但剛剛我們也提到了“程式員最讨厭的兩件事”，要求所有的開發人員都去主動的按照規範寫注釋，把所有的接口、參數清單的類型、描述等資訊全都寫清楚，是一件比較費時費力的事情。我們希望有一個能夠減少開發人員負擔的方法。
2、 現在不是有很多專業的API管理工具嗎，我直接用專業的API管理工具去維護也是可以的吧。
API管理工具我們也是有考慮的，但是有如下的問題：
• 很多工具依然缺少自動化的API生成；
• 不是專注于解決微服務領域的問題，随着服務量迅速上升，管理起來依舊比較困難。
3、 那微服務架構本身也會有提供相關的接口管理功能吧，Dubbo可以用Dubbo Admin，Spring Cloud可以用Spring Boot Admin，它們不香嗎？
這裡篇幅有限，我們不再去詳細講述開源工具我們怎麼去一步步使用，就用一張表格說話：
從表格可以看到，EDAS微服務治理的服務契約，支援版本更廣泛了，配置難度更低了，代碼侵入性沒有了，直接用EDAS的Agent方案，它不是更香了？
EDAS 服務契約實踐
下面我們來體驗一下，EDAS上如何檢視Spring Cloud的微服務契約。
建立應用
根據你的需要，選擇叢集類型和應用運作環境，建立Provider和Consumer應用。
服務查詢控制台
1、 登入EDAS控制台，在頁面左上角選擇地域；
2、 左側導航欄選擇：微服務治理 -> Spring Cloud / Dubbo / HSF -> 服務查詢；
3、 服務查詢頁面單擊某個服務的詳情；
檢視服務契約
服務詳情頁面包括基本資訊、服務調用關系、接口中繼資料、中繼資料等資訊。在“接口中繼資料”一欄，便可檢視服務的API資訊。當使用者使用Swagger注解時，會在“描述”列顯示相應資訊。
服務契約實作細節
在設計服務契約功能的時候，我們不但解決了開源架構中配置難度大，且部分方案具有代碼侵入性的問題，而且針對如下階段的難點都做了相應的方案，相信這些地方也是微服務架構的使用者會關心的：
1、資料擷取
• 擷取的同時是否還需要其他配置？
• 如何擷取所需的方法名及描述、參數清單及描述、傳回類型等資訊？
• 會不會影響服務的性能？
• 資訊能不能全面的拿到？
• 能不能同步接口的變更？
2、資料解析
• 能不能看到參數類型/傳回值類型的詳細結構？
• 解析參數結構的時候會不會影響啟動時間？
• 泛型、枚舉是否支援？
• 循環引用如何解決？
下面我們來詳細介紹一下這幾點都是如何解決的。
資料擷取
為了減少使用者的配置和使用難度，我們采用了Agent方案，使用者無需任何額外的代碼和配置，就可以使用我們的微服務治理功能。
Java Agent是一種位元組碼增強技術，運作時插入我們的代碼，便可穩定的享受到所有的增強功能。
而且通過測試可得，隻要在SpringMVC的映射處理階段，選取合适的攔截點，就可以擷取到所有的方法映射資訊，包括方法名、參數清單、傳回值類型、注解資訊。由于該點在應用啟動過程中隻發生一次，是以不會有性能的影響。
我們擷取的注解主要是針對Swagger注解。作為OpenAPI規範的主要指定者，Swagger雖并非是唯一支援OpenAPI的工具，但也基本屬于一種事實标準。注解解析的内容在表格的描述部分進行展示：
• Swagger2的注解解析（如@ApiOperation，@ApiParam，@ApiImplicitParam），解析value值在“描述”列顯示；
• OpenAPI3的注解解析（如@Operation，@Parameter），解析description值在“描述”列顯示。
當接口發生變更時，隻要将新版本的應用部署上去，顯示的服務契約資訊就會是最新的，無需擔心接口描述資訊不能同步的問題。
資料解析
如果參數清單/傳回值的類型是一個複雜類型，一般情況我們隻看到一個類型名。那麼有沒有辦法可以看到這個複雜類型的具體構成呢？
聰明的你可能就會想到，通過反射來遞歸周遊該類所有的Field，不就都解決了？思路确實如此，但實際要考慮的情況會更複雜一些。
以該複雜類型CartItem為例，它可能不但會包含基本類型，還可能會涉及到泛型、枚舉，以及存在循環引用的情況。
是以在解析該類型之前，我們需要先判斷一下該類型是否存在泛型、枚舉的情況，如果是，需要額外解析并存儲泛型清單及枚舉清單。
而循環引用問題，我們隻需借助一個typeCache即可解決。如下圖，A和B構成了一個循環引用。
如果我們不采取任何措施，遞歸周遊将永遠沒有出口。但是，如果我們在周遊A的所有類型之前，先判斷一下typeCache裡是否存在TypeA。對TypeB也以此類推：
那麼當周遊ObjB中所包含類型時，如果遇到了TypeA，同樣也會先判斷typeCache中是否存在。如存在，就無需再遞歸周遊ObjA中所有的類型了，而是直接記錄一個A的引用。是以，循環引用問題也就得以解決。
最終的解析資訊，可以在服務測試功能中得以展現。未來我們可能會支援直接在服務查詢中的服務契約頁，通過一個入口顯示複雜類型的具體解析結構。
由此我們看到，在服務契約的擷取及解析階段，涉及到的可能影響使用者體驗的問題都得到了一定的解決。
不止是服務契約
本文介紹了幾種接口描述方法，并且和開源架構的微服務接口管理功能進行對比，引出了EDAS服務契約。雖然服務契約看起來隻是在控制台上的一個接口資訊展示功能，但在未來的發展中不可或缺，其上報的關鍵資訊可以很大程度的優化服務測試、服務鑒權、标簽路由的體驗，是微服務治理體系中的基礎功能。
EDAS微服務治理在未來甚至還可以在服務契約的基礎上增加更多的增強功能，歡迎體驗。
除了 EDAS 和 MSE（微服務引擎）這些微服務産品之外，我們還有 ARMS (應用實時監控服務)、ACM（應用配置管理）、SAE（Serverless 應用引擎）等雲産品。歡迎加入我們一起，用心服務客戶，共同打造産品，讓業務永遠線上。
【更多精彩】
1．中間件爆款一折起，還有阿裡巴巴十年最佳實踐深度解密，點選馬上了解：
https://www.aliyun.com/activity/daily/commercial?spm=5176.20960838.0.0.6a54305etoEn4D2.【填問卷領淘公仔】點選馬上填寫問卷：
https://survey.aliyun.com/apps/zhiliao/YmW95Gk8bU【加入行業實戰交流釘釘群】
阿裡雲專門成立了“網際網路架構更新實戰課”釘釘群，每周邀請一位阿裡雲專家在群内進行行業最佳實踐直播，每天分享行業前沿幹貨，釘釘掃碼馬上加入。