ZanApi 让先后端协调更高效

1、当咱们在说先后端协做的时候，咱们在说什么

目前先后端分离已成为主流，先后端开发环境互相独立的状况下，如何提升先后端协做效率已然成为每一个公司不得不考虑的问题。

以一个项目开发周期为例，在协做上通常须要面对如下几个问题：

1. 项目开发初期，先后端须要就接口定义达成一致而且最好能在一个地方持久化，而且随着项目迭代开发持续维护
2. 先后端在并行开发时前端须要先对接口数据进行 mock
3. 项目联调前，对于前端同窗来讲，咱们须要能科学的判断后端同窗的接口是否真的达到可联调状态了

2、有赞以前是怎么作的

1. 对于接口定义

我相信不少公司跟有赞同样，没有专门的API文档站点，也没有相应的工具，基本在一个通用的文档站点由工程师本身手动建立、维护接口文档。

有赞也一样使用这种方式去维护接口文档，但这种方式会带来一些比较明显的问题：

1. 建立、维护成本大，在后端同窗比较忙的状况下，不见得能够及时提供、更新文档。
2. 手动编写容易出错。
3. 因为是通用的文档站点，接口文档展现并非很是直观。

这些问题都会增长协做双方的沟通成本，进而影响项目总体进度。

2. 对于数据 mock

前端同窗对于接口数据 mock 应该是很是熟悉的，并且每一个公司或多或少都会有本身的一些套路跟方案。

好比最开始，你们可能会使用在前端代码里面直接写死 mock 数据的方式。你可能会对下面这段代码比较熟悉：

import mockData from './mockdata.js'

// ajax(url).then(dosomething)
// 数据 mock

setTimeout(mockData => {
    dosomething(mockData);
}, 1000);
复制代码

经过这种方式，前端同窗能够在开发阶段手动 mock 后端接口数据，从而实现并行开发。

但这种方式的缺点显而易见：

1. setTimeout 显然是没法彻底模拟 ajax 的行为的。
2. 上线前须要修改代码，从新打包。
3. 由于有缺点2，会引入额外的风险点。（忘记修改从新打包）
4. 是否要保留 mock 数据和相应的逻辑以便以后项目迭代。
5. 若是后端接口变动，没法及时响应（依赖于先后端口头通知）

由于这些缺点和 nodejs 的崛起，前端同窗天然会想到使用 node 作一套 mock 服务器。因而就有了下面这种方式：

// ajax(realUrl).then(dosomething)

ajax(mockUrl).then(dosomething)
复制代码

这种方式解决了使用 setTimeout 模拟真实请求的问题而且极大的减小了 mock 功能对业务的侵入。并且由于 mock 数据在远程，先后端可同时修改，减小沟通成本。

可是这种方式仍是没法解决问题 2、3、4。

有赞就曾使用过这种方式的变体，咱们依赖特定 ajax 库的全局钩子，解决了问题 2、3、4。但却也带来了其余问题，好比对特定 ajax 库的强依赖。

3. 联调状态判断

我相信不少公司跟有赞同样，联调时间是在项目开始的时候开发预估的，开始联调的时候前端其实并不知道后端接口是否真的OK了，或者说至少能调通了。因此经常会碰到的问题是，后端同窗告诉你能够联调后，你发现接口报的全是 404 或者 500 ，最后一查是后端环境配置有问题。

其实有赞在以前也并无找到一个比较好的方案，到如今也只能说还处于探索阶段。

3、那么到底什么样的协做方式是咱们想要的

1. 对于文档来讲

1. 后端同窗能快速生成文档，而且持续维护。
2. 文档须要包含足够多的信息
3. 友好的接口定义展现

2. 对于数据 mock

1. 方便合做双方可同时修改，即时生效
2. 最好能够自动生成随机返回值
3. 能根据不一样的请求参数返回不一样数据
4. 修改 mock 数据的行为，能够快速通知到合做方，避免双方对数据格式认知不一样步

3. 对于更好的判断联调时间

经过比较科学的方式判断后端接口是否已经可被调用。

4、ZanApi 是如何作到的

首先，后端同窗在写文档这件事上，成本是否能够为零？

有赞目前在大力推动服务化，而且引入了 node 做为中间层。因此在有赞，先后端的边界变成了 browser + node -> java 服务化接口。

对于 java 同窗来讲，业界已经一些比较成熟的方案来生成接口文档，好比 swagger 、api blueprint 、swift。

但这些方案要么须要 java 同窗引入不少非项目的三方依赖，要么有它本身的一套接口定义方式从而增长 java 同窗的工做量。

并且有些方案并不适用于目前愈来愈主流的 browser & node -> 协议网关 -> java 服务化接口 这种先后端协做方式。

1. ZanApi 的文档生成方案

解决快速生成、更新文档的问题

为了让 java 同窗更方便的生成文档，咱们为 java 同窗提供了IDEA Intellij 插件。

最终的效果是，java 同窗可以一键生成、更新接口文档。

解决文档数据问题及展现

咱们在远程部署了一个 java 解析服务器，经过该解析服务，咱们能够将 java 代码里的备注抽取出来生成接口字段注释。最终一个接口的返回值定义多是这样的。

因此，若是 java 同窗自己有比较好的写注释的习惯，那么对他来讲生成一个合格的接口文档将是零成本的。

2. ZanApi的数据 mock 方案

目前有赞完整的数据 mock 方案如图所示：

从客户端（pc / mobile）发起的请求在通过 ZanProxy 过滤后，将须要 mock 的接口打到 ZanApi 上，通过 ZanApi 返回 mock 数据。

解决可同时修改，快速通知的问题

因为 ZanApi 部署在远端，先后端可同时修改，因此自己自然没有这个问题。

而且在 ZanApi 系统上，你能够收到本身收藏的接口的 mock 数据变动通知，能够较快的感知 mock 数据的变动。

支持多份 mock 数据，自动匹配

ZanApi 支持为同一个接口添加多份 mock 数据，请求在数据 mock 时，ZanApi 能经过请求参数，自动返回不一样 mock 数据。

支持根据接口定义返回随机数据

当 java 同窗经过 Idea 插件 自动生成接口文档时，ZanApi 会经过解析服务获取接口的返回值定义并自动讲定义转化成 JSONSchema 格式。

当须要返回随机数据时，ZanApi 能够根据接口返回值的 JSONSchema 定义产生随机数进而返回给客户端。

3. ZanApi 对联调的支持

在 ZanApi 上，你能够为每一个接口建立不一样环境下的测试用例。在测试用例的基础上，你能够以项目维度建立一个接口集合。

当接口集合建立完毕后，ZanApi 提供了 一键测试 功能。

一键测试功能会获取该接口集合内全部的接口，并将这些接口中定义的测试用例完整的跑一遍。若是其中某一个接口没法调通，那么 ZanApi 将提示你该接口测试失败。

甚至，ZanApi 容许你经过对比真实接口返回值和接口返回值定义（或者对比以前已存在的某个 mock 数据）来判断该接口是否符合预期。

好比，在接口的返回值定义中字段 count 是一个数字，可是 ZanApi 发现测试用例返回的真实数据中该字段是一个 string ，那么该测试用例也将不会经过。

UI以下：

5、最后

在有赞技术开放日上介绍了 ZanApi 后发现你们对 ZanApi 仍是有着比较大的兴趣。可是因为咱们还没有有时间整理开源相关的事宜，而且确实 ZanApi 还有不少不成熟的地方啊，因此 ZanApi 开源在短时间内应该没办法实现。

但咱们一直有开源的计划，并为之努力着