关于api:得物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 平台接口分类管理能力较弱，随着文档和分类的增多，文档的可维护性逐步变差，文档和业务的关系也逐步减弱。例如在大型项目中，上千的接口，数百的分类目录，文档的分类管理曾经失去了原有的能力。

最后接口的分类治理计划：

a. 手动创立分类，并保护一个类目映射关系，插件仍然应用原来的上传逻辑。

   毛病：须要频繁保护类目之间的关系，前期保护老本高。

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 基于现有的文档数据，提供了调试性能，免去了配置出入参的麻烦，次要个性如下：

1. 反对多环境配置： 用户能够提前配置多套运行调试环境，例如开发，测试，生产等多种环境，一键切换调试环境。
2. 免登陆配置： 通过账号的配置，能够主动获取 token，解决调试获取 token 的问题。
3. 公共参数配置： 配置私有 header 参数，缩小接口配置次数，节约配置工夫老本。
4. 调试场景：反对近程调试和本地调试。

• 基于文档的转换能力

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