本文是《微服务治理实践》系列篇的第四篇文章，主要分享 Spring Cloud 微服务框架下的服务契约。
前言
随着微服务架构越来越流行，越来越多的公司使用微服务框架进行开发。甚至不止是公司，连笔者的研究生导师都要对实验室的 Spring Boot 工程项目转型使用微服务框架了。随着时间的推移，服务量逐渐上升，小学妹吃不消跑来问我问题：
一姐，我来交接你之前写的项目啦，你什么时间方便我想问你一些问题。这么多微服务接口，感觉不知道从哪里去看会比较好呢。
我想了想自己刚入门时候写的垃圾代码，还没有注释，无语凝噎。
于是到周末，花了整整一个晚上的时间，终于给零基础学妹从众多接口的含义，到参数列表的解析，最后到讲解百度应该搜什么关键词，全方位视频指导。学妹十分感动：
一姐你太贴心了555，跟别人协作项目的时候，经常能讲上几句就不错了，然后我还是什么都不明白，改完接口也不及时告诉我。还是你最好了，后面还有什么不懂的我再来问你哦。
从以上场景，我们可以总结出使用微服务框架后，会带来的几点进度协同问题：
尤其体现在项目交接上，该问题对人员变动比较频繁的组织，如高校项目的准毕业生和新生交接、企业项目的外包人员交接，问题会显得更加突出。开发人员经常过于关注微服务的内部实现，相对较少设计API接口。
程序员最讨厌的两件事：1. 写注释 2. 别人不写注释
是不是经常想着写完代码再写注释，但真正把代码写完以后，注释/接口描述一拖再拖最后就没有了？
即使有了 API 文档，但由于文档的离线管理，微服务接口变更以后，文档却没有及时变更，影响协作人员的开发进度。
综上我们看到，我们不但希望所有的微服务接口都可以很方便的添加规范的接口描述，而且也能随着接口的变更及时更新文档。因此，我们需要服务契约来帮助我们解决这些问题。
为什么我们需要服务契约
首先我们来看服务契约的定义：
服务契约指基于 OpenAPI 规范的微服务接口描述，是微服务系统运行和治理的基础。
有人可能会问了，既然想要规范的描述接口，我有很多其他的方式啊，为什么我要用服务契约？
1. 我用 Javadoc 来描述接口然后生成文档不可以吗？
可以，但刚刚我们也提到了“程序员最讨厌的两件事”，要求所有的开发人员都去主动的按照规范写注释，把所有的接口、参数列表的类型、描述等信息全都写清楚，是一件比较费时费力的事情。我们希望有一个能够减少开发人员负担的方法。
2. 现在不是有很多专业的 API 管理工具吗，我直接用专业的 API 管理工具去维护也是可以的吧。
API 管理工具我们也是有考虑的，但是有如下的问题：
-
-
不是专注于解决微服务领域的问题，随着服务量迅速上升，管理起来依旧比较困难。
3. 那微服务框架本身也会有提供相关的接口管理功能吧，Dubbo可以用Dubbo Admin，Spring Cloud可以用Spring Boot Admin，它们不香吗？
这里篇幅有限，我们不再去详细讲述开源工具我们怎么去一步步使用，详情见表格：
从表格可以看到，EDAS 3.0 微服务治理的服务契约，支持版本更广泛了，配置难度更低了，代码侵入性没有了，直接用 EDAS 3.0 的 Agent 方案，它不是更香了？
EDAS 3.0 服务契约实践
下面我们来体验一下，EDAS 3.0 上如何查看 Spring Cloud 的微服务契约。
创建应用
根据你的需要，选择集群类型和应用运行环境，创建 Provider 和 Consumer 应用。
服务查询控制台
查看服务契约
服务详情页面包括基本信息、服务调用关系、接口元数据、元数据等信息。在“接口元数据”一栏，便可查看服务的API信息。当用户使用Swagger注解时，会在“描述”列显示相应信息。
服务契约实现细节
在设计服务契约功能的时候，我们不但解决了开源框架中配置难度大，且部分方案具有代码侵入性的问题，而且针对如下阶段的难点都做了相应的方案，相信这些地方也是微服务框架的使用者会关心的：
-
-
如何获取所需的方法名及描述、参数列表及描述、返回类型等信息？
-
-
-
数据获取
为了减少用户的配置和使用难度，我们采用了 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 的引用。因此，循环引用问题也就得以解决。
最终的解析信息，可以在服务测试功能中得以体现。未来我们可能会支持直接在服务查询中的服务契约页，通过一个入口显示复杂类型的具体解析结构。
由此我们看到，在服务契约的获取及解析阶段，涉及到的可能影响用户体验的问题都得到了一定的解决。
刘旖明，花名眉生，北京邮电大学计算机学院在读研究生，暑期作为阿里云云原生部门实习开发工程师，主要进行阿里云微服务产品的相关研发，目前关注微服务、云原生等技术方向。
特别推荐一个分享架构+算法的优质内容，还没关注的小伙伴，可以长按关注一下：
长按订阅更多精彩▼
如有收获，点个在看，诚挚感谢
下载文档
