得物 API一站式协作平台的一些考虑

背景

Netty+Nacos+Disruptor自研企业级API网关

download：https://51xuebc.com/

Mooncake是得物API一站式协作平台。从2022年3月份开端担任Mooncake，到如今曾经一年了，回忆这一年，Mooncake大的阶段上，总共阅历过两个版本:

(资料图片仅供参考)

1、Mooncake 1.0: 面向前端和客户端的mock平台，主要处理接口调用者的数据mock问题

2、Mooncake 2.0: 面向前后端的，交融了yapi和mock的一站式文档管理平台，从供需两端处理接口文档的流通效率问题

晋级后的Mooncake产品架构如下：

如上图所示，我们希望Mooncake是得物研发作态系统中的重要一环，为了完成这个目的，Mooncake不时新陈代谢，发布了许多重要功用，例如支持染色环境调试、业务迭代信息报表、支持Dubbo协议的mock等；打通了RDC、EP、CMDB、网关等平台。此外，Mooncake还提供了openAPI，向外生长，支持EP、DOP、APM等平台，让开发同窗在研发的各个阶段都能便当的经过文档停止顺畅的交流。

在这个过程当中，Mooncake详细做了什么，又为什么这么做，做了之后有什么用，针对这几个问题我简单的说一下我本人的考虑。

一切过往 皆为序章

2002年贝索斯曾经给亚马逊公布了一份mandate，这份指令是这样的：

从今天起，一切的团队都要以效劳接口的方式，提供数据和各种功用。

团队之间必需经过接口来通讯。

不允许任何其他方式的互操作：不允许直接链接，不允许直接读其他团队的数据，不允许共享内存，不允许任何方式的后门。

独一答应的通讯方式，就是经过网络调用效劳。

详细的完成技术不做规则，HTTP、Corba、PubSub、自定义协议皆可。

一切的效劳接口，必需从一开端就以能够公开作为设计导向，没有例外。这就是说，在设计接口的时分，就默许这个接口能够对外部人员开放，没有讨价讨价的余地。

不恪守上面规则者，一概开除。

谢谢；祝你过得高兴！

这份指令的动身点是，贝索斯以为人际沟通常常会形成组织执行不力，而他处理这个问题的方式，就是经过API，系统性的标准组织间的对话。 这个其真实当下很普遍的微效劳架构之下，曾经不是什么新颖事了，还有我们大量运用三方开放API，这些都是经过API来完成系统间的调用；

但是在当时，如何让人们承受这个计划，积极的参与进来，同时也预防API众多，是个很大的问题。为此贝索斯树立了一套指标体系，经过鼓励最终构成一套正向的持续演进和迭代循环。

这套指标体系，我们能够了解为是一种公司或者组织层面的基建。

1934年，美国经济大萧条时期，罗斯福处理经济危机的两大新政之一的以工代赈，经过大兴基建的方式，刺激消费与消费平衡。

为什么罗斯福选择经过基建的方式来提振经济，其缘由跟贝索斯这套指标体系是一样的缘由。在兰小欢《置身事内：中国政府与经济开展》一书中提到，基建有三个特性：

1、扩展公共效劳的范围 产生范围效益

2、进步信息沟通效率 降低信息复杂性

3、加强各方对资源的竞争 产生鼓励

由此可见，基建是能够降本增效，并且协助组织构成一个正向的循环。

2022年3月份之前，得物经过Yapi平台，沉淀的HTTP接口有数万个，这是过去七年间得物自然增长的API数量，这曾经是一个很庞大的数字，但是在这些http接口背后，还有数量愈加庞大的rpc接口散落在语雀、飞书，更有大量的接口没有文档沉淀，在历史中默默发挥着余热。

那么如何让文档标准起来，如何让更多的开发同窗把接口统一同来，如何让数量庞大的接口文档发挥更大的价值，Mooncake从三个方面提供效劳做了一次晋级:

1、从单一mock效劳晋级为盘绕接口文档的一站式协作平台，用户从前端和客户端扩展到效劳端、测试、前端、客户端

2、盘绕接口研发作命周期，经过插件、飞书音讯、一键mock、一键配置网关等一系列工具，进步信息沟通效率，降低前后端沟通复杂度

3、关联rdc提供迭代和团队两个维度的数据看板，经过文档质量分统计来刺激内部竞争，进而推进产出更高效的文档

接下来我从设计和技术两个层面简单回忆一下Mooncake这次晋级都是如何做的。

Mooncake的设计理念

Mooncake的晋级，我们遵照了尼尔森的十大设计理念：

1、系统可⻅性准绳

系统要在恰当的时间内给予用户恰当的反应，一直让用户晓得当前正在发作什么。 ——尼尔森

能够了解为包括⽤户在⻚⾯上的任何操作，系统需求给出相应的反应，来确保⽤户在操作过程中的状态可⻅、变化可⻅、内容可⻅，从⽽协助⽤户将交互引导到正确的⽅向，⽽不会糜费精⼒。 Mooncake经过按钮、音讯提示的即时反应，来响应用户的操作:

2、贴近场景准绳

系统要运用用户的言语，用户熟习的单词、短语和概念，而不是系统术语。遵照理想世界的商定，使信息以自然和符合逻辑的次第呈现。 ——尼尔森

⽤户会习气⽤理想世界中已有认知来对待问题，这个已有认知是⽤户依据⾃⼰控制的经历、学问和想象所建⽴的⼼智模型。 Mooncake这次晋级，交融了Yapi和Mock，除了技术底层在数据上的交融，交互上，也尽可能的保存了原有的交互习气，比方经过idea上传文档的习气，比方依照文档、编辑、运转、类型声明去组织页面tab:

3、可控性准绳

当用户错误地选择了的某个功用后，系统需求提供一个明白的「紧急出口」，来让用户分开其不想要的状态，而且无需额外的对话框，支持撤销和重做。 ——尼尔森

Mooncake里，经过多tab的方式，便当用户翻开多个接口文档，而无需频繁的刷新页面:

4、分歧性准绳

我们不应当让用户去疑心不同的语句、状态或操作能否在表达同一件事，设计需遵照平台的惯例。 ——尼尔森

⼀致性能够给⽤户统⼀的认知，协助⽤户快速学习、记忆和熟习产品的功用，从⽽建⽴⽤户稳定的⼼智模型。为了保证产品间的⽤户体验统⼀，通常都需求建⽴设计标准，来确保产品内部的⼀致性，这里的⼀致性包括视觉⼀致性、⾏为⼀致性和感知⼀致性。 Mooncake这次晋级，字体、颜色、尺寸规划、组件库都遵照了得物设计体系标准:

5、错误预防准绳

比报错提示更好的办法是，经过严谨的设计来避免错误的发作：要么消弭容易出错的状况，要么把这些容易出错的状况找出来，并在用户采取行动之前提供确认选项。 ——尼尔森

当操作不可逆时，给予⽤户⼆次确认的时机，防止⽤户由于误操作形成的结果:

6、系统辨认胜过记忆

经过将对象、操作和选项停止可视化，最大限度地减轻用户的记忆担负，用户不需求记住对话框中某一局部到另一局部的信息，系统操作的指示信息需求易于被用户发现和获取。 ——尼尔森

⽤户是不可能记住操作过程中的过多信息的，Mooncake提供了我的珍藏和最近访问协助同窗们快速找到本人常用的项目文档:

7、运用的灵敏性和效率

一些快捷操作的功用，固然会被新手用户疏忽，但可能为专家用户所运用并协助提升其运用效率，因而，系统需求同时满足新手用户和专家用户的需求，允许用户频繁地操作。 ——尼尔森

这⼀点其实是在B端产品设计中⽐较容易无视的⼀个准绳，我们常常默许使⽤产品的是相对成熟的产品使⽤者。 Mooncake的菜单栏提供折叠和展开两种形式，并且会记住用户上次的选择，关于新同窗，默许展开菜单，便当理解平台的功用；关于曾经熟习Mooncake 的同窗能够收起菜单，文档的可视区域最大化，便当阅读:

8、美观和简约设计

对话框中不应包含无关或很少用到的信息，在对话框中每增加一个信息，就意味着降低了主要信息的相对可见性。 ——尼尔森

Mooncake的对话框，都尽可能的降低复杂度，一次只做一件事情，一次只搜集最重要的数据，并且尽可能的提供下拉选框减少用户输入:

9、协助⽤户发现、判别和修复错误

报错信息应该用浅显易懂的言语表达，而不是用代码，精确地反响问题，并且提出可行的处理计划。 ——尼尔森

10、人性化协助准绳

协助文档的信息应该易于被搜索，聚焦于用户的任务，并列出详细的步骤，而且，不能太庞大。 ——尼尔森

Mooncake提供全局搜索、一键进飞书答疑群、自助协助文档协助同窗快速的找到文档，定位问题:

Mooncake的技术架构

在这次晋级之前，我们调研了一些业界关于API管理的理论，总的来说包含两大块内容：工具战争台。

4.1 工具向左

工具是轮子，处理当下的问题，是消费力工具；

Mooncake 提供了一系列工具：

1、针对java开发的IDEA插件，针对golang开发的CLI工具，协助开发同窗快速的上传文档

2、掩盖 webpack、vite以及阅读器的代理插件，协助前端同窗便当的完成数据mock

3、掩盖iOS和android的客户端代理工具，协助客户端同窗mock数据

4、掩盖前端和客户端的抓包工具，用来快速的生成mock数据

4.2 平台向右

平台的作用就是，经过一系列的资源整合，让平台内的资源相互作用，不时的磨合，发明出新的消费力工具。

在Mooncake平台化的过程中，遵照了两个准绳：

第一是多元多维。这个概念来自穷查理宝典，Mooncake 交融打通了EP、CMDB、RDC、网关等平台，最大限度的发挥文档的价值，也最大限度的降低研发同窗在API沟通上的本钱。

第二分而治之，各个击破。架构自身是处理问题的过程，问题太复杂了，只能采用分而治之的方法。

怎样分？应用金字塔原理，同时在数据化上做考虑，之后依照架构主题做拆分。Mooncake平台分为文档、用例、Mock三大块，盘绕这三大块停止晋级和优化。同时依照组织架构和迭代，停止数据统计和剖析，提供各种指标协助研发同窗权衡项目的文档质量。

怎样击破？Mooncake采用了分层架构，优先处理文档的问题，盘绕文档做深度；在处理了文档问题之后，在文档上下游和用例上持续迭代优化，经过openAPI的方式拓宽平台广度。

Mooncake的将来

假如说Mooncake 1.0是青铜时期，2.0是白银时期，那么接下来一定是Mooncake的黄金时期。

5.1 青铜时期

1.0的Mooncake 掩盖了得物前端平台一切用户，以及接近50%的客户端用户。

5.2 白银时期

2.0时期的Mooncake交融了yapi+mock，同时打通rdc、EP、网关平台等平台，在研发流程的各个阶段提供接口文档效劳，共沉淀了数万接口，掩盖了得物技术部90%的研发同窗，平台的NPS也一度到达57%。

5.3 黄金时期

目前的API建立、平台研发都还有很多问题：

1、在进度压力下，一些由于幸运心理而遗留的技术债，比方网关环境和项目环境的切换，比方swagger定时扫描等等

2、一些屈服于短期目的的计划，比方简单版本的diff功用，比方简单版本的文档迁移功用等等

3、一些由于途径过长而放弃的远大目的，比方dubbo的调试，比方文档驱动开发等等

将来Mooncake还能够做很多，关于API体系建立、关于平台化、关于开放，Mooncake将不时推进产品和技术的创新和晋级，为技术部的小同伴提供更好的产品和效劳。