得物API一站式协作平台探索与落地

1. 现状

API文档作为公司研发重要的数据资产，承载了公司核心的业务逻辑，随着公司业务的复杂化，软件架构微服务化，公司数字化的发展，API的研发管理成为了公司研发的最重要的一个环节，而得物目前存在两个接口文档相关的平台：

• 文档管理平台-YApi

基于开源的YApi平台，提供基础的API管理能力。

• 数据Mock平台-Mooncake

Mooncake 平台为前端和客户端提供零侵入、场景化的Mock服务。

2. 面临的问题

根据行业报告显示，开发团队大概有50%的工作时间是围绕着API开展的，目前在得物的研发流程中，围绕API文档的协同工作分散在不同的工具或者平台，导致现有的API在研发协同工作中低效流转。

• API文档资源利用率低

YApi作为现有的文档管理平台，过度的管控、复杂的交互和混乱的分类导致现有的文档利用率非常低。根据数据统计，大部分的使用场景为上传文档、确认文档等。

• API文档质量无法保障

由于YApi文档管理平台缺乏文档的最终测试环节，导致接口在后期改动环节，并不能及时同步到文档平台，最终无法保障文档的统一性和质量。

• 围绕API研发流程割裂

在接口的整个研发生命周期中（设计-开发/Mock-联调-验收），涉及到服务端、前端/客户端、测试多个角色，跨越YApi、Mooncake、测试平台等多个平台。

3. 业务思考

优质的API能够进一步的提升团队的研发效率，进而达到降本提效的效果。那么在这样的背景下，解决团队之间API的内部流转，解决前后端基于文档的工作对接，提升文档的研发利用率和文档质量成为了平台升级的核心问题。因此，文档和测试便成了核心环节，基于这样的思考，我们提出了文档驱动和测试驱动两个核心点，最终驱动整个研发流程的运转。

• 文档驱动：服务端完成接口文档、测试用例，前端、客户端能够通过接口文档了解接口定义以及应该如何跟接口进行交互，各职能团队参照API文档独立完成需求研发。

• 测试驱动：每个迭代，交付的接口文档都通过测试保证文档质量，对于测试不通过的文档，则要持续的改进，最终保证文档交付。

基于文档驱动和测试驱动，我们提出了DTDD(Document & Test Driven Development)研发模式，通过对DTDD模式的探索，打通了整个研发流程，实现了研发流程的闭环。

在DTDD模式下，平台要做的事情也就很清楚了：

• 沉淀API数据资产：沉淀具备业务价值分类的API接口文档资产，产生规模化业务价值。
• 测试驱动开发：同步自动化测试平台针对API的测试用例，提高API交付的质量。
• 实现数据Mock：基于API的数据Mock，提升前端、客户端的研发效率。
• 丰富文档能力：围绕API的使用场景，提供文档类型转换，接口调试能力。
• 降低沟通成本：基于消息通知机制，降低沟通噪音和信息复杂性，产品平台价值。

4. 解决方案

明确了DTDD研发模式的目标之后，接下来就是要如何去做了，通过对业界主流的API文档管理方案的调研，结合得物目前的现有平台YApi和Mooncake，我们最终决定打通两个平台，同时对功能进行了升级。平台的架构如下图所示：

Mooncake平台的研发并不是一蹴而就的，下面我们从数据分类治理、提升文档利用率、提升接口交付质量、降低用户沟通成本、降低平台使用难度五个方面讲述一下Mooncake研发过程中的一些思考。

4.1 数据分类治理

分类/分组从本质上，寻找事物的共同点和不同点，是我们认识和理解世界的基础方法和能力，合理的分类/分组可以帮我们更好的理解事物的共同点，帮助我们判断、推理，最终才能形式概念做出决策。

YApi原有项目分组和文档分类比较混乱，API文档作为业务资产不能很好的帮助研发理解业务，无法做到很好的提效，为了更好的辅助推动业务研发迭代效率，我们废除了原来的项目分组和文档分类，如何进行合理的项目分组和文档分类成了面临的问题。

• 项目分组：

最初我们想到的是按照公司组织架构对现有的项目文档进行分组，但是由于组织架构存在频繁调整的问题，通过调研我们发现与项目紧密关联的RDC 业务域相对稳定，最终我们将项目文档和业务域关联，将现有的项目文档按照业务域进行划分。

我们获取项目最新上传的十个接口，获取接口的维护人员，查询维护人员的归属业务域，通过计算不同业务域的权重，将项目按照计最大的业务域权重划分业务域分组。

示例：

记人员为A， 下面所获取的业务线为{[a, 80],[b,60], [c,10], [d, 5]} 

记人员为B，下面所获取的业务线为{[a, 60],[b,30], [e,10]}

// 业务线a
weight_a = (80+60)/2 = 70
// 业务线b
weight_b = (60+30)/2 = 45
// 业务线c
weight_c = (10+0)/2 = 5
// 业务线d
weight_d = (5+0)/2 = 2.5
// 业务线e
weight_e = (10+0)/2 = 5

weight_a > weight_b > weight_c = weight_e > weight_d

通过对项目数据的清洗，对YApi原有的项目进行了业务域的划分归属，也达到了以下目的：

• 通过对项目进行业务域的分组，可以更清晰的获取项目的相关业务属性。

• 默认选中用户归属业务域，降低用户获取信息成本。

• 接口分类：

YApi 平台接口分类管理能力较弱，随着文档和分类的增多，文档的可维护性逐渐变差，文档和业务的关系也逐渐削弱。例如在大型项目中，上千的接口，数百的分类目录，文档的分类管理已经失去了原有的能力。

最初接口的分类治理方案：

1. 手动创建分类，并维护一个类目映射关系，插件依然使用原来的上传逻辑。

     缺点：需要频繁维护类目之间的关系，后期维护成本高。

b. 使用贝叶斯算法，根据服务、接口名称、接口路径等构建分类关系。

     缺点：分类效果不明确，需要不定期筛选、维护不准确分类的接口。

通过对后端团队的调研，对现有的接口分类能力进行了以下的优化升级：

• 废弃原来的分类，提供多级分类的能力。

• 支持原有数据的批量分类能力。

通过为用户提供灵活的多级分类能力，使得接口分类具备更深层次的业务能力，对于项目文档资产的沉淀，起到了很好了帮助。例如在门店项目中，我们能很清晰的理解接口的业务能力，如图所示：

4.2 提升文档利用率

• 基于文档的数据Mock

围绕API文档前后端的对接，自然离不开数据Mock。根据文档字段，平台提供了一键Mock功能，依据文档字段，可以生成更精准的Mock数据，例如image、time、name、city等生成相关的数据。除此之外，我们提供更强大的Mock功能：

• Mock空间的数据隔离：通过提供更灵活的私有场景集，和更稳定的公有场景集，保证了Mock数据的安全性和数据隔离。

• Mock接口的多场景：同个接口提供不同的数据Mock场景，用户可以自己定义Mock场景数据，例如404场景，支付成功场景等，一键激活场景或者切换场景。

• Mock插件的零侵入：目前市面上常见的Mock服务，要么自己在业务代码中编写Mock数据，要么提供的插件侵入工程的业务代码，Mooncake平台基于Chrome插件提供零代码侵入Mock功能。

• 基于文档的调试能力

目前对于接口的调试，大家还是常用Postman进行调试，配置URL和参数的过程还是比较麻烦的，文档变更之后，还不能及时的进行改变。Mooncake基于现有的文档数据，提供了调试功能，免去了配置出入参的麻烦，主要特性如下：

• 支持多环境配置：用户可以提前配置多套运行调试环境，例如开发，测试，生产等多种环境，一键切换调试环境。
• 免登陆配置：通过账号的配置，可以自动获取token，解决调试获取token的问题。
• 公共参数配置：配置公有header参数，减少接口配置次数，节约配置时间成本。
• 调试场景：支持远程调试和本地调试。

• 基于文档的转换能力

YApi提供的文档转换能力较弱，无法判断字段的是否必填，在对前端的调研中，发现大家现有的转换能力不满意，导致功能的使用率较低，然而文档的转换能力在前端的使用过程中是个高频功能，手动转换比较浪费时间，因此我们丰富了文档的转换能力。

• 多文档类型支持：支持多种文档类型的数据转换，包括Schema 、JSON、Raw 类型等。

• 更精准的字段定义：根据字段的是否必填，在 TypeScript 中直接转换字段是否可选。

• 更多语言的支持：目前支持类型声明转换为TypeScript 、Java 、Swift 、Go 、Kotlin 、Dart 等。

通过丰富基于文档的内容和功能，Mooncake平台提升了文档的利用率。在Mooncake平台推进的最近三个迭代，同比原有的YApi，人均PV提升2倍，使用时长提升23倍。

4.3 提升接口交付质量

DTDD最重要的一个核心测试驱动，通过接口文档的测试，保证文档的交付质量。在Mooncake平台，将接口文档的数据同步到自动化测试平台，测试编写接口的测试用例，Mooncake平台将测试用例同步过来，开发在交付文档前，可以通过跑测试用例，确保接口的交付质量。

开发可以在Mooncake查看当前用例的参数设置，同时也可以运行用例查看用例执行结果，如下图所示：

4.4 降低用户沟通成本

整个研发流程围绕API文档的生命周期进行，因为牵涉到不同的职能角色(前端，后端，测试，客户端)等，所以接口的变更会影响到整个研发链路。围绕接口变更的频繁沟通，或者由于接口变更没有及时通知到其他角色，影响整个研发进展的事情时常发生，基于这样的考虑，我们增加了以下特性：

• 接口订阅：通过订阅关心的接口，可以实时收到接口的变化通知，一键查看接口变更。

• 历史版本：平台记录了接口变更的历史版本，可以很方便的查看当前版本与历史版本的区别。
• 群消息通知：平台增加了基于webhook的群消息通知功能，项目接口文档的增删改变化都能收到机器人的通知。

4.5 降低平台使用难度

子曰：工欲善其事，必先利其器。工具的重要性不言而喻。为了使得平台使用起来更方便，提升工作效率，我们配套Mooncake平台，提供了如下的工具链：

• 前端工具：抽离前端代理SDK，服务与不同项目配置的代理插件，包含Webpack插件 、Vite插件、Umi插件、Chrome插件等。如图所示：

• 后端工具：

• IDEA插件：提供交互式IDEA插件，降低代码侵入，增强对文档分类的约束。

• Go命令行工具：基于社区的Go文档生成工具，将Yaml文件一键上传到指定项目。

• 本地调试工具：提供本地调试工具Chrome插件，解决本地调试跨域问题。

通过对DTDD模式的探索和思考，最终完成了得物一站式文档协作平台的自主研发，Mooncake一站式文档协作平台的上线只是起点，绝不是终点，对于文档平台的展望如下图所示，通过文档协作平台的建设，推动业务发展，进而实现产生经济价值的目的。

• 基本功能: 围绕API提供基本的功能，例如接口文档、接口测试、数据Mock等

• 解决方案: 围绕API的一些功能，为研发提供解决方案，如研发流程的管理、API的快速生成、接口编排、依赖信息变更等

• 降本提效:  基于API的扩展性方案，体验研发流程效率，降低生产成本，推动业务发展

5. 总结&思考

本文简要给大家介绍了Mooncake作为得物一站式研发协作平台的演进过程。平台的整合需要深度思考整合前的现状以及最终要解决的问题，对于最终想要的产品，首先要进行充足的调研，充分了解用户目前的痛点，做到调研先行，明确目的，本着提出问题、解决问题的核心，打磨好每个细节、每个功能。

目前Mooncake平台已经实现文档的管理功能，后续平台的方向我们也在规划：完善Dubbo协议的支持和调试；定时扫描代码，实现文档的自动化更新；丰富文档依赖的上游信息，做到变更通知；接口编排实现业务数据的组装等。

*文/migor

 关注得物技术，每周一三五晚18:30更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～