接口管理及前端mock数据工具调研

[bigbigbo]

我们需要一个什么样的接口管理方案？

实际开发中，前后端配合可能存在以下几个问题：

• 当后端接口未实际生产出来的时候，前端又有接口方面的需求，即mock能力
• 没有详细的接口文档给前后端开发带来一些不必要的工作量
• 接口更新了，前端却不知道
• 最好本身集成了测试能力

此时我们就希望通过一个方案或者一系列工具，解决以上的问题：

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 因为业务特性，最好是具备本地部署的能力

已有的方案或者工具介绍

• 以下有打钩的代表满足该需求，反之不满足该需求。
• 个人看法主要以上手体验、mock能力、接口描述这三方面进行开展性描述。
• 推荐指数满分5分。

1、NEI-接口管理平台

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力

个人看法：整个流程下来很繁琐，mock能力也很弱，测试也需依赖浏览器插件

推荐指数：★★

2、DOClever

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力

个人看法：上手简单，mock能力够用，接口描述能力够用，额外还提供版本管理的能力

推荐指数：★★★★

3、Aapizza

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力

个人看法：这东西很像postman，感觉不是想要的接口管理工具，mock由mockjs提供支持，接口描述够用

推荐指数：★

4、Yapi

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力

个人看法：操作简单易上手，mock能力由mockjs提供，支持富文本描述接口，另提供强大的测试集功能，也支持从其他数据中（postman、swagger）导入接口，同时满足用户权限管理和支持本地部署，基本满足我们的方案需求

推荐指数：★★★★★

5、SosoApi

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力，==但是收费==

个人看法：近乎可以理解为是swagger-editor的plus版，支持mock，基础功能都是基于swagger，另外本地部署需要收费。

推荐指数：★★★

6、Eolinker

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力，但开源版本移除掉了一些线上的功能

个人看法：操作还是挺易于上手，mock和response分离让操作的成本增加了一些，项目文档也和接口分离也提高了操作成本

推荐指数：★★★

7、Easy-mock + swagger

• ui和操作一定要简洁
• 提供mock的能力
• 提供接口描述
• 接口模块管理
• 团队管理 + 消息通知
• 接口测试能力
• 支持本地部署的能力

个人看法：这个方案需要结合easy-mock和swagger，easy-mock只提供mock的能力，提供从swagger导入接口的能力，关于接口管理这一块就全部交给了swagger来处理。

和上述的方案相比，在使用成本上可能（只是可能）会高一些，因为如果想提供一致的接口数据，就只能由后端人员来提供swagger的配置文件，但个人认为这也是比较合理的，但此方案缺少了团队管理这一块，其余的问题都可以归类到一系类工具搭配使用和使用一个完整的服务之间的问题。

推荐指数：★★★★

总结

以上7种方案，比较推荐Yapi和Easy-mock + swagger。

其中Yapi基本满足了我们所有的方案需求，并且也支持swagger导入接口数据。所以理想的开发方式，由后端提供swagger提供配置文件直接导入数据，前端人员制造需要的mock数据，文档描述需要前端人员或者后端人员再一次书写。

而easy-mock + swagger，基本就是需要开两个窗口来完成写作了，需要mock在easy-mock上写数据，想测试接口想看接口的request和response信息，则需要切换到swagger窗口，工具配合使用无法避免会出现这个问题。前后端协调和Yapi一样。

对比	Yapi	Easy-mock + swagger
上手难度	即使你不懂开发，上手也是没有难度	涉及到工具配合使用，成本会稍大
mock能力	由mockjs提供	由mockjs提供
接口描述	支持富文本	easy-mock本身的描述只限于文本另需借助swagger
接口模块管理	支持	由swagger提供，在easy-mock中不具备模块管理的能力
团队管理 + 消息通知	支持	不支持
接口测试能力	方便好用的测试功能	由swagger
本地部署	支持	支持

如果需要一个接口管理的平台，则推荐Yapi，如果前端只想要mock，后端只需要必须的接口信息（request和response），easy-mock + swagger也足够了。

但是如果后端不想使用swagger（在代码中写注解，可能不太优雅，只用swagger-editor的成本也挺大，网友表示书写一份json或者yaml的swagger配置也是挺繁琐的），Yapi是首选。

[bigbigbo]

另附yapi调用mock不完全指南

如何调用mock接口

1. 在 js 代码直接请求yapi提供的 mock 地址（不用担心跨域问题）

let prefix = 'http://yapi.xxx.com/mock/2817'
$.post(prefix+'/baseapi/path', {username: 'xxx'}, function(res){
    console.log(res) //返回上图预览部分的数据
})

不推荐使用此方法，如果前端需要切换到真实环境的接口，成本比较大

2. 基于本地服务器反向代理

• 通过webpack-dev-server提供proxy

// 此时如果访问/api/users实际访问http://yapi.xxx.com/mock/2817/api/user
proxy: {
    "/api": {
      "target": 'http://yapi.xxx.com/mock/2817',
      "changeOrigin": true,
    }
},

• 基于 nginx 反向代理

location /api
{
	proxy_pass   http://yapi.xxx.com/mock/2817/api; #api后面没有"/"
}

---

现有的项目基本都基于webpack构建，所以通过webpack提供的proxy的使用成本最低，所以这里推荐使用通过webpack-dev-server提供proxy

如何切换至prod接口

• 设置一个变量，通过变量的值来切换代理的对象

// 新建一个config.js，键入以下内容
module.exports = {
    mock: true,
    apiHost: {
        mock: 'http://yapi.xxx.com/mock/2817/api',
        prod: 'http://www.prodenv.com/api'
    }
};
// webpack.config.js
const config = require('./config.js');
const apiHost = config.mock ? config.apiHost.mock : config.apiHost.prod;
/* ... */
proxy: {
    "/api": {
        "target": apiHost,
        "changeOrigin": true,
    }
},

• 设置两个代理对象，然后包装ajax方法通过传递参数来切换mock和prod接口
  首先是设置代理对象：

proxy: {
    "/mockApi": {
    	"target": 'http://yapi.xxx.com/mock/2817/api',
        "changeOrigin": true,
    },
	"/api": {
		"target": 'http://www.prodenv.com/api',
    	"changeOrigin": true,
	}
},

然后包装一个ajax中间件

// config.js
module.exports = {
	mock: true
}
// request.js
import config from 'config'
/* ... */
function request(...args) {
    const len = args.length;
    const requestParams = len > 1 ? args.slice(0, len - 1) : args;
    let [url, options = {}] = requestParams;
    const [mock] = len > 1 ? args.slice(-1) : [false];
	if (config.mock) {
		const API_PREFIX = mock ? '/mockApi' : '/api';
		url = API_PREFIX + url;
		// 如果想返回不同期望的mock数据，则request最后一个参数传入类型为string的状态值
		if (typeof mock === 'string') {
			url += `?mockStatus=${mock}`;
		}
	}
    
	/* ... */
	return fetch(url, options)
	.then(checkStatus)
	/* ... */
}

简单调用的时候

const request = require('./request);
request('/users') // 此时isMock默认为false，调用真实接口
request('/users', true) // 此时isMock为true，调用mock接口
request('/users', {}, true) //此时isMock为true，调用mock接口

如果想返回不同期望的mock数据，
首先在YApi中的高级mock中新建一个期望，

如图所示，参数过滤会以query的方式拼接在url上，我们在此新建了一个mockStatus=error的期望，接着我们只要在我们的前端请求中加入相应的mockStatus就可以了

const request = require('./request);
//此时mockStatus等于error，最后的请求地址是/mockApi/users?mockStatus=error，返回我们期望为error的数据
request('/users', {}, 'error')

---

两种方法都可以，第二种方法会更灵活些，可以自己决定哪些接口要mock哪些不要。如果有其他mock使用的方法，欢迎提出。