永不放弃 2019-06-27
目前前后端分离已成为主流,前后端开发环境互相独立的情况下,如何提高前后端协作效率已然成为每个公司不得不考虑的问题。
以一个项目开发周期为例,在协作上一般需要面对以下几个问题:
我相信很多公司跟有赞一样,没有专门的API文档站点,也没有相应的工具,基本在一个通用的文档站点由工程师自己手动创建、维护接口文档。
有赞也同样使用这种方式去维护接口文档,但这种方式会带来一些比较明显的问题:
这些问题都会增加协作双方的沟通成本,进而影响项目整体进度。
前端同学对于接口数据 mock 应该是非常熟悉的,而且每个公司或多或少都会有自己的一些套路跟方案。
比如最开始,大家可能会使用在前端代码里面直接写死 mock 数据的方式。你可能会对下面这段代码比较熟悉:
import mockData from './mockdata.js' // ajax(url).then(dosomething) // 数据 mock setTimeout(mockData => { dosomething(mockData); }, 1000);
通过这种方式,前端同学可以在开发阶段手动 mock 后端接口数据,从而实现并行开发。
但这种方式的缺点显而易见:
因为这些缺点和 nodejs 的崛起,前端同学自然会想到使用 node 做一套 mock 服务器。于是就有了下面这种方式:
// ajax(realUrl).then(dosomething) ajax(mockUrl).then(dosomething)
这种方式解决了使用 setTimeout 模拟真实请求的问题并且极大的减少了 mock 功能对业务的侵入。而且因为 mock 数据在远程,前后端可同时修改,减少沟通成本。
但是这种方式还是无法解决问题 2
、3
、4
。
有赞就曾使用过这种方式的变体,我们依赖特定 ajax
库的全局钩子,解决了问题 2
、3
、4
。但却也带来了其他问题,比如对特定 ajax
库的强依赖。
我相信很多公司跟有赞一样,联调时间是在项目开始的时候开发预估的,开始联调的时候前端其实并不知道后端接口是否真的OK了,或者说至少能调通了。所以常常会碰到的问题是,后端同学告诉你可以联调后,你发现接口报的全是 404
或者 500
,最后一查是后端环境配置有问题。
其实有赞在之前也并没有找到一个比较好的方案,到现在也只能说还处于探索阶段。
通过比较科学的方式判断后端接口是否已经可被调用。
首先,后端同学在写文档这件事上,成本是否可以为零?
有赞目前在大力推进服务化,并且引入了 node
作为中间层。所以在有赞,前后端的边界变成了 browser + node
-> java 服务化接口
。
对于 java 同学来说,业界已经一些比较成熟的方案来生成接口文档,比如 swagger
、api blueprint
、swift
。
但这些方案要么需要 java 同学引入很多非项目的三方依赖,要么有它自己的一套接口定义方式从而增加 java 同学的工作量。
而且有些方案并不适用于目前越来越主流的 browser & node
-> 协议网关
-> java 服务化接口
这种前后端协作方式。
为了让 java 同学更方便的生成文档,我们为 java 同学提供了IDEA Intellij 插件
。
最终的效果是,java 同学能够一键生成、更新接口文档。
我们在远程部署了一个 java 解析服务器
,通过该解析服务,我们可以将 java
代码里的备注抽取出来生成接口字段注释。最终一个接口的返回值定义可能是这样的。
所以,如果 java 同学本身有比较好的写注释的习惯,那么对他来说生成一个合格的接口文档将是零成本的。
目前有赞完整的数据 mock 方案如图所示:
从客户端(pc / mobile)发起的请求在经过 ZanProxy
过滤后,将需要 mock 的接口打到 ZanApi
上,经过 ZanApi
返回 mock 数据。
由于 ZanApi 部署在远端,前后端可同时修改,所以本身天然没有这个问题。
并且在 ZanApi 系统上,你可以收到自己收藏的接口的 mock 数据变更通知,可以较快的感知 mock 数据的变更。
ZanApi 支持为同一个接口添加多份 mock 数据,请求在数据 mock 时,ZanApi 能通过请求参数,自动返回不同 mock 数据。
当 java 同学通过 Idea 插件
自动生成接口文档时,ZanApi 会通过解析服务获取接口的返回值定义并自动讲定义转化成 JSONSchema
格式。
当需要返回随机数据时,ZanApi 可以根据接口返回值的 JSONSchema
定义产生随机数进而返回给客户端。
在 ZanApi 上,你可以为每个接口创建不同环境下的测试用例
。在测试用例
的基础上,你可以以项目维度创建一个接口集合
。
当接口集合
创建完毕后,ZanApi 提供了 一键测试 功能。
一键测试功能会获取该接口集合
内所有的接口,并将这些接口中定义的测试用例
完整的跑一遍。如果其中某一个接口无法调通,那么 ZanApi 将提示你该接口测试失败。
甚至,ZanApi 允许你通过对比真实接口返回值和接口返回值定义(或者对比之前已存在的某个 mock 数据)来判断该接口是否符合预期。
比如,在接口的返回值定义中字段 count
是一个数字,但是 ZanApi 发现测试用例返回的真实数据中该字段是一个 string
,那么该测试用例也将不会通过。
UI如下:
在有赞技术开放日上介绍了 ZanApi 后发现大家对 ZanApi 还是有着比较大的兴趣。但是由于我们尚未有时间整理开源相关的事宜,并且确实 ZanApi 还有很多不成熟的地方啊,所以 ZanApi 开源在短期内应该没办法实现。
但我们一直有开源的计划,并为之努力着