乐趣区

关于api:得物-API一站式协作平台的一些思考

背景

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 将一直推动产品和技术的翻新和降级,为技术部的小伙伴提供更好的产品和服务。

本文源自得物技术官网:tech.dewu.com

退出移动版