开源项目 yapi 产品和技术总结
发布于 2 个月前 作者 suxiaoxin 666 次浏览 来自 分享

总结了下 yapi 接口管理开发过程中用到的技术和遇到的坑,分享给大家。

yapi 是什么

YApi 是一款多人协作的 api 管理平台,提供了 api 文档管理,api 数据 模拟(Mock),调试和自动化测试 api 等功能。主要解决前后端分离带来的以下痛点:

  • 接口文档不可靠。很多小伙伴管理接口文档,有使用wiki的,有word文档的,甚至还有用聊天软件口口相传的,后端接口对于前端就像一个黑盒子,经常遇到问题是接口因未知原因增加参数了,参数名变了,参数被删除了。
  • mock 数据生成方案没有统一出口。我们都有这样的经历,前端开发功能依赖后端,解决方案有自己在代码注入json的,还有后端工程师临时搭建一套测试数据服务器,这种情况下势必会影响工作效率和代码质量,也不能及时进行更新。
  • 资源分散,无法共享。接口调试每个开发者单独维护一套Postman接口集,每个人无法共用其他人的接口集,存在大量重复填写请求参数工作,最重要的是postman没法跟接口定义关联起来,导致后端没有动力去维护接口文档。
  • 集成 api 自动化测试困难。yapi 提供了可视化的 api 自动化测试方案,只需要简单的填写参数,增加断言,就能实现 api 自动化测试。

核心原理

yapi 后端选用 koa, mongoose 技术栈,使用 mvc 基础架构,过程大概是 Client(view) 发起 http 请求,经过 Router 模块处理后,转交给 baseController,baseController 验证了用户的身份后,执行相应 Controller 的业务逻辑,controller 只处理业务逻辑,数据从相应的 Model 拿取。处理完成后,再由 controller 将数据发送给 view 层。

image

遇到的问题和解决方案

1. 如何定义接口 Body 数据?

image

做 YApi 产品设计时,遇到第一个问题是如何定义 Body 数据。当时参考了很多竞品,大多是通过 form 表单维护一个 json 的描述。如果 body 非常复杂,有上百个字段,基于 form 表单去维护效率是很低的,很可能导致后端或前端不去维护字段的更新。yapi 独创了 json5 方案,用注释描述字段,效率提升多倍。

2. 怎么满足大型企业权限管理?

yapi 参考了gitlab扁平化,权限设计,即满足了大型企业级,项目的管理,又保证了效率和易用性

image

3. 怎么实现跨域请求?

  • 基于谷歌浏览器扩展 (目前的方案)
  • 本地代理 (使用成本高,需要单独在自己机器安装代理服务器,弃用)
  • 服务器代理(因无法代理到内网机器,弃用)

参考nei和apizza.cc chrome扩展实现原理,他们是通过content_scripts脚本绑定原网页dom事件,操作原网页dom来实现的,谷歌扩展跟业务代码强制耦合到了一起。这样做的坏处就是网页升级必需强制用户安装的谷歌扩展也跟着升级,很容易导致不兼容的问题。

image

基于以上问题,YApi在开发时,实现了一个crossRequest扩展,是基于chrome扩展能够跟页面共享dom的原理开发的,降低了跟项目代码的耦合,即便项目代码有改动,扩展不需要做任何改变

4. 如何设计一个插件机制?

YApi 内在的功能不可能满足所有公司的需求,需要一个完善的插件机制提供功能上的增强和扩展。下面是 YApi 插件机制设计图:

image

未来计划

从 YApi 1.0 开源到现在,已经收到了很多朋友的赞和 github star(500+)。YApi 马上要开始三期的开发了,目前正处于需求调研阶段,如果大家有这方面的需求,可以在 github 上提一下,下面是最新收集到的需求:

  • yapi 默认集成 ldap 登录方式
  • yapi 做一个 sso 登录插件,基于现有的 qsso 改造成大多数公司可用的
  • 接口运行参数值支持 函数表达式,支持可视化选择 mock 参数和 变量参数
  • 接口运行支持加工运行前后的 request 和 response ,主要是处理加密的接口或各种 token 参数问题
  • 接口集可支持服务端代理,配合 jenkins 实现契约型测试
  • 以项目为维度的自动化代码生成功能,默认提供一些 js,java, php 等语言相关框架的模板,可高度自定义生成模板
  • 支持 dubble 等 rpc 接口定义
  • 支持对 response header 定义
  • 增加接口改动历史功能
  • 版本管理(实现方式还未想好)
  • 接口文档按分类组织接口
  • 接口文档备注支持 markdown
  • 环境设置支持全局 header 和 自定义变量

yapi 官网

http://yapi.qunar.com

回到顶部