开源地址
https://github.com/XiaoMi/mone/tree/master/miapi-all/mi-api 欢迎对云原生技术/研发效能感兴趣的小伙伴加入(Fork、Star)我们。
背景
目前软件技术领域生态丰富，各类产品与技术蓬勃发展。互联网行业目前主流技术架构普遍基于微服务的协作式研发。在微服务研发的协作体系中，微服务接口文档、测试、Mock等相关协作环节的自动化、智能化能力是决定研发交付效率的关键一环，MiApi 则用于改善，填补该环节的空缺与不足。
什么是MiApi
市面上第一款集成了多类型 RPC 接口自动化管理、自动化文档生成、接口测试、mock、团队文档等功能模块的一站式平台。重新定义了微服务接口的开发交付流程，致力于提供最好的接口治理服务，更大程度提高开发效率。并已取得相关软件著作权《Mi-Api一站式微服务接口维护平台》与相关技术专利《一种基于注解的RPC接口文档自动生成技术》。
我们面临的问题
之所以决定立项做这件事儿是因为我们的业务研发在服务接口交付时切实的存在几个痛点：
极高的接口对接成本
对多种协议（如Dubbo、Grpc）微服务接口开发文档生成能力缺失，人工撰写文档极度耗费开发人员人力、时间、精力，版本难以控制、修改难以追溯，接口改动/协同成本极高。
互相阻塞的调试过程
微服务接口开发过程中缺乏测试/调试工具，提供方与使用方之间无法提前 mock 数据，互相阻塞开发进度。
持续交付能力的缺失
接口/项目文档管理混乱，缺乏较好的聚合、持续交付以及长期维护能力。
而市面上目前主流的几款接口管理软件如 YApi、Swagger、Postman等等...几乎都无法兼顾我们面临的这几项痛点，对于多协议，自动化生成的支持都较为薄弱。
基于以上痛点，我们决定自主设计、研发一套完整的、更加自动化、流程化、智能化的解决方案，以下本文将对项目进行详细介绍，以及对于一些痛点问题我们是如何解决、如何设计的。
核心流程与能力
核心流程
为了做到整个服务接口交付过程 90% 以上的自动化，我们设计了一套基于注解的在线接口定义交付流程，即研发人员将在服务接口的定义阶段，根据自身需求为需要对外提供能力的接口添加基础注解说明，完成接口定义后，运行服务，在平台中即可直接搜索选取自身服务，加载保存。由于目前主流微服务项目大多基于Java下的 Spring/Springboot 框架，因此本项目方案主要针对 spring 框架项目。当然，我们同样支持以手动方式来添加维护接口。
保存过程中平台将基于自动解析获取的接口的基本信息以及研发人员自定义的选项说明等生成该接口的基本示例、mock数据等等。同时，在加载保存后即可直接使用生成的请求用例来调试相应接口，或者进行接口mock。
主要流程如图：
核心流程图
核心能力
对于整个平台而言我们重点提供了以下几项较为核心的能力：
多协议服务接口支持
平台提供了对 Http/Https、Dubbo、Grpc 等 RPC 协议类型接口的配置维护的支持。 包括但不限于对各种协议类型接口文档的自动化生成、接口 mock 数据的自动化生成与自定义、接口的远程调试等。
对于在项目中已添加依赖，注解的服务，皆可在平台中直接搜索选取加载（加载过程将进行自动化的文档数据生成）。
平台使用示例
一键测试与mock
对于以上支持的协议类型下的服务接口，在平台中都支持使用平台生成的用例数据直接进行调用、调试。同时，平台也将对维护的接口生成相应的 mock 数据与调用mock的地址。
快速分享
项目中维护的接口可以通过自定义聚合集合的方式生成接口集合链接分享给调用方，同时也支持直接生成 pdf格式文件进行转发。
技术与架构
上述介绍了接入平台的核心流程与平台提供的核心功能，以下将对平台的整体设计以及一些核心能力的技术方案做详细说明。
整体架构
技术架构图
服务接口信息的加载生成
对于不同协议类型的接口，我们关心的接口信息可能不完全一致。对Http来说，我们可能需要关注该接口的url路径、请求方式、出入参数等。而对于Dubbo接口来说，我们可能更关注该接口的服务名、方法名、出入参类型、服务版本、分组等。总体而言，对于大多数服务接口，接口的入口、出入参这些信息都是我们需要关心的，而这些数据的获取则需要对业务项目从接口层、方法层、参数层进行解析。
因此，我们针对不同的协议类型的服务项目提供了相应的解析包，在服务运行后，通过可选的开关选项，决定是否对项目进行扫描解析，若启用，则在业务项目 spring 容器整体初始化完成之后，触发扫描器（扫描器的具体设计实现将在后续进行介绍），对项目服务、接口、参数等进行扫描解析，并缓存解析数据。
项目数据扫描解析完成后，组件将把缓存的数据推送至主体平台，平台根据一定规则存储这些接口数据，从而业务研发人员即可在平台中搜索相应服务数据，根据自身需要选择、加载、生成指定的服务、接口文档。
接口加载流程图
维护接口的调试与Mock
除了生成服务的接口文档之外，在开发过程中，研发人员还需要对指定的接口进行 mock 或调用测试。
关于调试，在接口文档的生成过程中，平台将根据解析到的接口基本数据生成一些请求示例、请求参数用例等，这些数据在文档中都会体现。研发人员可以在不进行任何额外配置与参数编写的情况下，通过平台的测试引擎，对不同协议类型接口直接进行调用，对于不同协议类型的接口调用底层实现方式有所区别，具体如下图所示：
测试的流程图
对于 mock 来说，不同协议接口的mock也有所区别。例如 http/https 协议的接口，平台将直接生成该接口的 mockUrl，调用方直接调用该 url 即可获取该接口的 mock 数据。而对于 dubbo 服务接口来说，调用方一般基于服务方提供的 api 包进行调用，因此需要进行特殊处理拦截转发 dubbo 调用请求，获取平台生成的 mock 数据，整体如下图所示：
接口mock流程图
因此，为了实现上述描述的功能，平台整体将由提供给业务项目引用的依赖包、交互平台、Mock服务器几个组件构成。
核心组件
业务依赖包
为了获取上述我们所需的业务项目接口的基本数据，我们需要业务方引入我们提供的一套依赖包，针对不同协议接口的服务我们提供了针对性的依赖包，例如对提供 Http 接口、Dubbo接口的项目，我们分别设计提供了适配 Http、适配 Dubbo 的依赖包。这些包将用于不同协议接口数据的解析、数据推送、服务注册等等。
适配不同协议的依赖包在具体解析等实现上有所区别，但整体结构基本一致，所有包都由注解模块（annos）、核心模块（core）、缓存模块（cache）构成。
其中，注解模块（annos）提供了包括启用文档生成的开关注解、服务接口层级的定位注解、方法层级的定位描述注解以及字段层级的描述注解以上4个核心注解。具体注解的作用在技术方案的注解定义中将详细介绍。
核心模块（core）主要提供了扫描器（scanner）以及相关实现工具类。该模块是整个MiApi的核心，它用于扫描解析业务项目接口，获取、解析服务、接口的基本信息如方法名、出入参等数据。具体实现同样在技术方案中的扫描器模块加以说明。
缓存模块（cache）则用于暂存扫描器（scanner）扫描解析到的基本数据，用于后期的数据推送等。
主体平台
主体平台是用户交互的入口平台项目，它提供了一些基本的包括团队管理、接口管理、文档管理、接口数据生成、多协议接口测试等模块功能。当然，平台最重要的能力是承接来自各地、各方业务项目的数据推送，包括业务的心跳注册（用于实时在线数据，技术方案中将做介绍）、接口基本数据推送，并基于接收到的这些基本数据生成例如请求用例、mock数据等等，并将生成好的数据以一定规范组织聚合成对用户友好的文档页面内容。
Mock服务器
Mock服务器是较为独立的一个模块，它的主要功能是接收存储平台基于接口数据生成的、或者研发人员自定义的mock数据，以及承接来自各方的mock请求，根据请求的路径、参数、以及一定的规则进行匹配最终返回指定接口的mock数据。对于不同协议接口的 mock 调用逻辑不完全一致，具体将在技术方案中的Mock数据生成与调用拦截中进行介绍。
总结
本文介绍了关于 MiApi 项目的研发背景、平台提供的主要流程与能力以及一些核心能力的设计思考，关于本项目更多的技术细节与实现我们将在后续文章中陆续进行分享。