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

持续创造，加速生长！这是我参与「日新计划 10 月更文挑战」的第2天，点击检查活动详情

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根据现有的文档数据，供给了调试功用，免去了装备收支参的费事，首要特性如下：

• 支撑多环境装备： 用户能够提前装备多套运转调试环境，例如开发，测验，出产等多种环境，一键切换调试环境。

• 免登陆装备： 经过账号的装备，能够主动获取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