基于Swagger的前后端协同开发解决方案-SMock

avatar
UX @京东
原文链接: mp.weixin.qq.com

相信所有人在开发实践中都会去摸索怎么来提高前端开发效率,怎么提高前后端协同的默契度。本文会给大家介绍这一摸索过程及其中的一个小成果SMock,让大家在摸索过程中少走弯路。

开发背景

项目时间紧、业务复杂、任务重,大概所有人都会碰到这种项目,这种情况不会允许你有丝毫怠慢。所以前后端并行开发,在并行过程中有这样一种场景:后端数据服务还并未开发完成,我们却已经将所有页面重构及基本交互完成,此时我们不能就此等待后端的开发完成,这样是多么浪费生命。我们会根据后端的接口文档自己模拟数据来支撑我们做一些数据交互的开发,但是模拟数据这一步骤在针对一个有上百个接口的项目中是一个超级大的工程,并且枯燥无味无内涵。

当前解决方案

方案一: 乖乖的将所有模拟数据及模拟数据路径自己手动敲出来,我猜你肯定不会这么傻干的;

方案二: 采用网络中模拟数据平台如mocky,但在这样的平台上还是会有很大的复制粘贴的工作量,并且生成的模拟数据路径是随机生成的,你还得去生成两套数据请求路径;

方案三: 也有模拟数据平台可以解决随机生成的路径问题,如easy-mock,这种平台对于你的数据及请求路径做到了可持久化。但是这样的平台一般都会需要注册登录权限,甚至需要配置数据库,那么你的模拟数据及数据路径就将会放置于别人的服务中。这个操作过程本身就很复杂,同时你放心这么干吗?数据放置于他人服务里,安全吗?

“所以SMock来了”,为了减少这个模拟数据阶段的开发成本,提高开发效率,SMock的目标产生了。它需要解决的具体问题就是将模拟数据批量自动产生,并让这些模拟数据置于可访问的服务中,这样就解决了当前开发的一些症结,不需要手动书写模拟数据,不需要用他人的模拟数据平台服务。SMock将会消除掉上面几个方案的弊端,让你开心快乐放心的工作。

Swagger与SMock

前面提到后端将接口文档给到前端,他们是以Swagger的文档形式提供给前端的。有人要问,Swagger是什么?那么且听我先给大家介绍下Swagger。 Swagger是SMock的好伙伴,SMock需要依赖于它。官方表示:Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。可以用于接口文档的在线自动生成,还可用于功能测试。在和我们合作的后端部门中,我们常常会推荐他们使用Swagger。主要是太好用了,比硬生生编写的WORD文档或者是PDF要好很多,我专门列了一下它的优势。

  • 可以随时同步后端人员的修改;

  • 接口格式统一;

  • 方便测试接口;

  • 参数及参数规则清晰;

  • 接口内容直观;

上个图给大家感受下:

有了后端人员的Swagger文档,SMock便可以发挥它的作用了:分析Swagger文档数据,生成mock数据,启动mock服务。服务置于本地,不用担心数据泄露。如此,项目便可以快速的进行数据交互开发了。

细述SMock

前面的描述是不是还是不太知道SMock到底是个什么鬼?先一句话概括下吧,SMock是基于Swagger的自动化mock数据平台。然后跟着我的自问自答了解下它具体是什么。

SMock能干什么?

  • 对Swagger文档进行数据抓取并转为mock数据

后端给到前端的是Swagger文档,我们要模拟数据的话,需要将Swagger文档里所给出的信息变成前端需要的数据。SMock可以自动化这个过程,对Swagger文档的数据进行抓取。下图是SMock将数据抓取后处理后的结果。

  • 启动本地服务器

在创建了mock数据的基础上,SMock同时启动了mock数据的服务,以便本地开发中可以访问。这个本地的服务就替代了前期的后台服务无法支撑我们进行数据交互层开发的等待期,而后期后台服务真正开发完成后,又能很快的衔接上,不需要修改接口路径。

  • 生成接口聚合文件

通常一个项目会涉及到几十甚至几百个接口,如果是手动去写入咱们的项目中是不是感觉也是个工作量不小的的事情?而SMock会帮我们自动生成所有接口路径的聚合文件,这个文件可以直接让我们运用于项目开发中,甚至还可以指定该文件的生成位置,连拷贝工作都可以帮我们省掉。下图中是生成的所有接口路径的部分截图,其中红框框起来的便是我们切换模拟数据接口和真实数据的开发,简单来说就是通过浏览器的访问路径中是否有“debug”字样来切换。

  • 接口数据校验

当我们在项目中使用SMock后,SMock还会帮我们对接口访问的正确性进行校验。具体校验的内容有:

  • 验证路径及接口类型是否有误,如果有误便无法访问数据

  • 验证入参的完整性。如果少一个必输参数,将返回错误的信息

  • 验证入参内容格式正确性。参数类型如果不正确,将会返回错误的信息

SMock有什么优势?

  • 使用简单,配置一至两个参数即可使用

  • 随用随启动,控制方便,无权限限制

  • mock了数据的同时将服务也开启

  • 减少手动书写代码工作量

  • 可以让前端前期的数据环境更接近真实环境,让后期切换真实环境更方便

  • 一次聚合所有接口,方便项目接口路径统一管理

  • 小而美,专注解决定向问题,没有鸡肋功能在其中

SMock怎么用?

用以下三步便可开启SMock之旅。

第一步:将SMock模块安装至Node环境中

  1. npm install jdcfe-smock -g

第二步:初始化SMock.json的参数,也就是访问Swagger文档的相关参数

  1. smock init

第三步:生成mock数据,启动mock服务

  1. smock run

第四步:项目中使用接口请求即可有返回数据

  1. http://127.0.0.1:3000/api/xxxx

关于第二步更详细的参数配置,可移步官网[1]查看相关文档。

SMock的整体流程?

上面细碎的讲了很多,下面来跟着我一起看一下SMock的整体流程。

  • 研发首先提供自动化的接口文档,推荐使用Swagger,Swagger可以跟随研发接口变化而同步,避免接口信息不同步的情况。

  • SMock动态从Swagger文档网站抓取所有接口,包括URL,返回数据等。

  • SMock将抓取到的接口返回数据全部自动创建成JSON文件,并且存储于自定义的目录下。

  • SMock将所有的接口URL汇总到一个JS文件中,并且根据启动的服务器,动态生成isdebug开关。

  • SMock根据接口文档中的URL创建接口,并且根据文档内容,返回对应的JSON文件,并且将生成的URL文件创建到对应项目的路径中。 

SMock命名来由?

因为最初是基于Swagger来mock数据,同时我们想到了要让mock数据变得更简单(Simple)。所以我们取了Swagger和Simple的首字母“S”,然后和“mock”拼接在一起,这让人在用到Swagger的时候很容易就能想到这个工具,而我们也会一直保持着让开发变得更简单的初衷继续前行。

SMock的痛点

太依赖于Swagger。然而这个痛点实际上可以转化为一个项目效率提高的催化剂,为什么呢?因为将这个问题克服后可以帮助项目提高整体的开发进度,克服方案就是前端人员可以建议后端去尝试使用Swagger。前面也提到了很多Swagger的好处,这促使大家将传统文档形式的数据接口共享方式改为Swagger文档形式,这种结果会使后端使用起来比较省心,不用总是手动更新WORD文档,同时前端也希望有这种能实时更新并清晰直观统一的文档给到自己。 大家都受用,何乐而不为呢? 当然这个痛点也不会长期持续,后面我们可能还会计划新增支持多种文档格式,还有支持自定义数据等功能。期待我们后续的更新。

项目实战

SMock最初是使用在我们一个项目非常紧急的大型项目中试水。当然也是出自于那个项目,是那个紧急项目促使了SMock的产生。当时该项目工期紧张,前后端并行,并且采用前后端分离的方式。后端很快提供给了我们Swagger文档,大批量的模拟数据全部由SMock完成,并且很完美的在项目中被调用,到后期前后端数据接口联调时,切换开关无缝对接。后面组内的小伙伴们也纷纷开始使用于其他多个合适的项目中。可以说SMock在这些项目的开发效率上起到了很关键的作用,减少了很多mock的成本,提高了人效。

未来规划

SMock虽然是起源于我个人一个想走捷径的念头,但是它后期的稳定及健壮将由我们团队共同来支持,并且现在已经由团队在共同协作维护及完善,感谢这些为之付出的小伙伴们。后续我们还将会提供可用于Webpack配置的插件,让用户的高效方式变得更多元化,同时还提供云端构建能力,让用户无需本地安装。当然最重要的是不仅仅局限于基于Swagger文档,还可以自定义模拟数据、自定义接口等。同时还……不,不能再说了,不然透露的太多了。

广告硬植入

以上介绍有没有让你心动?快快跟着我的脚步去试用起来吧,SMock必将减少你的加班时长。

SMock相关详细使用手册可在官网查看,可使用NPM安装到本地,源码是开源的。如果小伙伴们在使用过程中遇到问题或是有更好的建议可以跟我们联系。

更多精彩内容请关注我们团队的公众账号“全栈探索”。

扩展阅读

[1] https://smock.jd.com

[2] https://github.com/jdf2e/SMock

[3] https://www.npmjs.com/package/jdcfe-smock

相关文章推荐