得物 API 元数据中心探索与思考
一、背景
目前市面上针对 API 的管理平台很多,但由于各种客观因素,这些平台的功能都更多聚焦在 API 文档的消费侧。而对于 API 文档的生成都非常依赖开发人员的手动创建,很难保障文档的实时性和有效性。市面上常见的 API 管理平台,由于缺乏有效的管理机制,完全依赖开发人员的主动维护,在文档体量变大之后就出现了文档归属混乱、文档重复上传、文档信息更新不及时等问题。
由于文档缺乏有效的维护,很大程度上局限了 API 文档在消费侧的作用。举个例子,如果一份 API 文档更新不及时,那么前端就很难基于过时的文档进行数据 Mock。如果平台大多数的文档都存在更新不及时的问题,那其他的平台也很难把平台的 API 文档作为有效信息使用。
二、Mooncake API 文档维护
为了解决文档的维护问题,得物技术部自研了 Mooncake 平台,并从文档组织规范、文档生成效率等方面做了大量的尝试。
API 文档组织规范
平台用户对于接口文档的存储管理、交付时间和交付质量均有一定的诉求。平台通过规范的方式统一起来,建立接口文档项目和目录组织规范,降低接口查找难度和用户使用费力度。
规范应用名称
如果应用名称可以任意创建,从技术部现有数据看来,各域定义的巨大差异将会导致用户使用存在一定的理解成本。为统一项目命名规范,同时更清晰的展示接口与项目之间的关系,平台计划与发布平台 &CMDB&网关等系统保持一致,统一采用 CMDB 中的应用名作为项目名称,降低文档查找的难度。
通过打通 CMDB 数据,统一 CMDB 应用名,打通与公司内部平台的数据,主要包含:
建立与发布平台的关系,自动获取应用染色环境列表,降低接口调试难度;
建立与 Gitlab 平台的关系,自动获取应用需求迭代数据,降低文档与需求绑定的费力度;
建立与网关平台的关系,一键同步接口网关自动关联路由组等数据信息;
打通交易网关、APM 的数据,获取接口文档信息,丰富文档信息密度。
通过将应用名称规范化,Mooncake 平台建立了一个规范化的应用命名体系,让用户可以更方便地查找和使用文档,并提高了团队的协作效率和产品质量。
规范文档分类
如果以类名或注解作为文档分类的依据,导致文档的可维护性逐渐降低,文档和业务的关系也逐渐削弱。为了解决这个问题,平台通过规范文档的分类,降低文档的查找和管理难度。
在技术层面上,提供多级分类能力,规范化维护文档分类,并完成商家、客服、供应链、交易等规范性分类的推动以及约束文档的落地;
在规范层面上,推进各个团队根据自己的业务场景按照统一的规范来分类文档,从而提高文档的可维护性和管理效率。例如,推动客服、商家、交易等各个域落地接口目录规范文档,项目负责人或 Owner 定期检查分类规范的执行情况,并对分类不规范的文档进行整理和优化。
通过技术和规范手段相结合,规范文档分类,可以降低文档的查找难度,提升文档的可维护性和管理效率。
API 文档生成
MooncakeUpload Idea 插件
得物技术部研发的 MooncakeUpload Idea 插件可以帮助解决 API 文档创建和录入的问题。该插件通过解析 Java 项目里的注解和注释,实现了一键生成 API 文档的功能,降低了 API 文档创建的费力度。相较于手动创建接口文档,使用插件上传 API 文档所需的时间仅为几秒钟,而且规范了接口的分类属性,使得上传文档过程更加简便和快速。在每个迭代中,使用插件可以节约将近 667 小时的时间。
实现原理
基于 IntelliJ Platform 自身的基础架构,依靠 PSI(Program Structure Interface)核心特性,通过分析解析出来的语法树可以获取准确的代码信息,例如获取文件中包含的类、方法、字段和注释等信息。
核心实现
配置信息
通过 IntelliJ Platform 提供的虚拟文件系统(Virtual File System)功能,读取插件的信息配置,主要包括 Mooncake 的项目信息,人员的域账号等。从而能够获取 Mooncake 的分类数据,以及接口的变更人员。
原有的配置功能,会通过用户配置的项目名称信息和当前路径进行二次校验,增加了用户理解的难度,平台插件使用的问题中,80%的问题来源于配置的繁琐。因此在 2.0 版本之后,通过内置数据校验,降低了项目信息的配置难度,配置信息仅需一个参数即可:
出入参信息
依靠 PSI 核心特性,通过解析选中文件的语法树,提取字段信息,组装 API 文档的出入参和注释,主要核心逻辑:
可视化面板
Mooncake 平台支持 API 文档的多级分类,为了降低接口文档的分类难度,降低对代码的侵入,基于 Java 的 Swing GUI 库,我们提供了可视化操作面板,用户可以选择需要上传的接口和分类信息,以及需求信息。
版本更新
MooncakeUploadApi 上传插件是得物技术部自主研发的插件,由于存在公司的业务信息,无法上传到插件市场,只能将插件打包成 Jar 文件给开发使用。这种情况下,可能会出现以下问题:
用户无法及时感知到插件修复过的版本,导致升级新版本时存在困难。如果出现问题,用户还需要找 Mooncake 维护人员定位问题,并进行手动修复和更新,维护成本比较高;
由于不能上传插件市场,用户升级插件需要手动找到 Mooncake 维护的插件文档,并下载相应的 Jar 包进行更新,费力度高。
针对以上可能存在的问题,得物技术通过搭建私有仓库方式,最终实现了插件更新方案,如图所示:
最终实现了插件启动的自动检查版本更新,并进行通知。
结果
通过自研 Mooncake Idea 上传插件,实现 Mooncake 平台以下收益:
快速响应并定制化需求:通过打通 Gitlab,插件可以根据代码分支来自动绑定接口的业务需求,以便快速响应相关问题;
提升开发效率:使用插件可以大幅度降低 API 文档创建的成本和负担,从而让开发人员更加专注于代码的开发和测试等任务中;
规范 API 文档:插件通过可视化面板交互方式,规范了文档的格式和内容,并能够快速选择上传的文档分类和字段信息,以便更好地管理和使用 API 文档信息,从而提高了规范化程度。
目前研发部门接通过插件每个迭代上传 API 文档的次数(如图所示),平均每个迭代产生数千次的变更,大大提升了维护文档效率,达到降本提效的目的。
基于 Gitlab MR 自动解析
背景
平台提供了 API Upload 插件之后,整个文档生产端现状如下:
服务端在开发阶段通过手动/插件上传 API 文档到 Mooncake 侧;
提测节点时从网关同步当前迭代新增的 API 接口,与 Mooncake 侧接口比对,查看是否存在,不存在则要求开发上传接口。
通过网关来进行新增接口卡点,可能存在以下问题:
网关侧配置的接口仅为需要走网关流量的接口,不走网关的接口,如 Dubbo 接口、内部接口并不能保证接口在 Mooncake 存在;
即使在 Mooncake 存在的接口,如果在上传之后又产生了变更,通过网关的卡点并不能保证最新的变更也同步到了平台。
因此,平台在通过上传插件降低 API 生成费力度的同时,也需要将现有的研发流程仍然强依赖使用者的习惯、API 文档的质量不稳定的风险考虑进去。
针对这个问题,平台在 Gitlab 的流水线中,新增了一个自动解析代码的节点。对于每个向 release 分支合并的 MR,将其中和接口定义相关的部分进行解析并自动在平台生成/更新对应的 API 文档,从而保证所有接口在发布前一定将最终的接口定义同步到 Mooncake 平台。
实现
配置 Gitlab 流水线任务
自动解析需要拉取项目的全量代码和依赖包代码,因此占用的内存空间较大;
自动解析项目耗时较长,例如公司内部某个项目,7k+的文件需要耗时 3.5min,自动解析 feature 分支消耗太多资源。
因此我们最终针对 HTTP 接口只做每个迭代的兜底,通过解析 Release 分支,保障每个迭代结束时,文档都是完整的和最新的。
获取二方包源码
由于二方包在编译为 Jar 之后,代码的注释会丢掉,而 API 文档需要解析字段的注释和注解来描述字段的含义,自动解析要保证接口的完整性,需要补全二方包的注释。因此我们扫描了 Pom 文件的依赖包,并将公司的二方包全部下载到当前项目目录里面,并反编译解析原始数据。
获取公司内所有的二方包源代码数据:
解析项目所有的代码
通过调研,Qdox 工具包具备体积小,解析效率快,使用文档简单的特性,因此采用使用 Qdox 将项目中的所有代码解析为 Java 语法树,并实现 API 文档的信息提取。
核心逻辑如下代码所有,解析所有 class,并基于 Swagger 注解和 RestController 注解提取所有的 Http 接口。
而接口文档信息的解析与 Idea 插件解析思路基本一样,最终将所有的接口方法解析为 JSON 格式的 API 文档,如图所示:
将解析的接口数据与 Mooncake 平台数据对比
接口在 Mooncake 不存在的,直接上传到 Mooncake 平台,保证 API 文档的完整性;
接口存在的,比对接口文档核心数据,包含出入参和路径等,不一致则更新接口文档,保证 API 文档的一致性。
三、Mooncake API 元数据中心
Mooncake 平台通过不断完善从生产到消费链路的信息,延长 API 文档的生命周期,完成 API 文档元数据中心的闭环。在平台的探索过程中,逐渐沉淀了丰富 API 文档信息,解决了 API 的利用率低,API 信息密度低的问题。目前,API 信息主要包含以下:
API 描述信息:如 Swagger、OpenAPI 等格式的 API 描述文件,包括 API 名称、版本、路径、参数、响应等;
接口规范:定义 API 请求和响应协议,规范接口分类;
稳定性:API 的版本管理、生命周期、周期变更率等数据;
文档和示例:API 的使用文档、示例代码、调用等;
开发平台:提供 API 开发者所需的工具和 SDK,例如 IDEA 插件、Go cli 等;
研发流程规范:提供接口版本周期稳定性数据,例如:调试是否成功、自动化测试用例等。
通过打造得物 API 元数据中心,更有效的提高 API 开发和管理效率,使得 API 能够更加透明化、可靠化、易于使用。基于丰富的 API 文档信息,平台围绕调试、Mock、数据开放等 API 消费侧的功能也做了大量的探索尝试。
调试
由于平台沉淀了精确的接口字段定义,因此基于这些定义对接口进行调试自测就非常方便。在提供基础调试功能的同时,平台也通过以下手段对调试的体验进行了优化:
基于文档信息,自动填充入参字段信息;同时基于文档信息进行简单的类型校验;
通过同步 CMDB 应用名称,自动获取染色环境名称,支持调试自动填充染色环境参数;
打通内部核心平台,优化接口签名和鉴权问题,降低接口调试难度。
对于部分仍然习惯于使用 postman 进行调试的用户,平台也支持将 postman 调试记录进行一键同步。
之所以这么执着的推动大家到 Mooncake 来进行调试,主要是期望将调试记录作为研发完成自测的一种“凭证”,并将其同得物现有的研发协同面板系统进行结合,把“自测凭证”作为生成前后端联调单的前置条件,通过保障联调过程中的接口质量从而提升联调效率。
整个联调过程大致如下:
Mock
由于项目接口的完整性和及时性,前端可以基于平台的 Mock 功能,在开发阶段,前端可以 Mock 需求下的所有接口,充分完成功能的自测,前置联调流程,降低因为后端延迟提供接口的带来延期的风险。
基于入参字段的准确性和完整性,在 Mock 数据过程中,平台可以校验入参的信息的准确性,包括是否完整,数据入参类型是否准确等,提前发现问题,提升前端交付质量。
通过 API 文档的调试功能,平台沉淀了基于接口文档的真实数据,因此,平台可以自动为前端提供更加精准的具备业务属性的数据 Mock,以及不同的异常状态码数据场景,更加真实对页面场景进行还原。
API 元数据平台
将公司所有的 API 文档收敛到 Mooncake 平台,通过保障接口的完整性和及时性,可以保障所有消费平台都能拿到接口的详细信息,同时通过与其他平台协作,将接口的不同维度信息收敛到平台信息,例如接口的等级、读写属性等,丰富文档的信息密度。
通过提供 OpenApi,为公司内部平台提供 API 信息,例如:
提供 API 文档包括接口名称,字段语义,出入参完整性给 APM 监控平台,提升 Trace 链路的可读性;
提供完整的出入参信息,与流量平台的接口数据比对,及时发现接口版本问题;
提供接口的变更率、是否调试成功等数据给提测平台,作为质量管控数据面板的一部分;
提供接口相关联的域名信息给网关平台,作为网关平台监控接口流量信息的依据;
将接口信息提供给接口自动化平台,可以提升测试编写接口测试用例效率。
四、展望
目前得物面对日益增长的业务,尤其是涉及分布式架构、微服务等技术和架构时,通过 API 元数据中心集中化管理 API 接口文档,在协同管理各团队、保证接口的一致性和完整性、快速演进变更、降低沟通成本等方面有着至关重要的作用。后续,平台依然会围绕已经沉淀的 API 信息,在接口自动化测试、API 文档管理、接口健康度监控等上下游领域进行持续的探索。
*文 / migor
本文属得物技术原创,更多精彩文章请看:得物技术官网
未经得物技术许可严禁转载,否则依法追究法律责任!
版权声明: 本文为 InfoQ 作者【得物技术】的原创文章。
原文链接:【http://xie.infoq.cn/article/026e9c5810b8f63a3570d97cd】。文章转载请联系作者。
评论