文档章节

为什么前后端分离了,你比从前更痛苦?

谢小呆
 谢小呆
发布于 10/16 09:01
字数 1978
阅读 11866
收藏 20

你有没有遇到过:

  • 前端代码刚写完,后端的接口又变了。

  • 接口文档永远都是不对的。

  • 测试工作永远只能临近上线才能开始。

为什么前后端分离了,你比从前更痛苦?

  前后端分离早已经不是新闻,当真正分离之后确遇到了更多问题。要想解决现在的痛,就要知道痛的原因:

为什么接口会频繁变动?

  设计之初没有想好。 这需要提高需求的理解能力和接口设计能力。

  变动的成本较低。

  德国有句谚语:“朝汤里吐口水。” 只有这样,才能让人们放弃那碗汤,停止不合理的行为。前后端同学坐在一起工作的时候效率会有提升,当后端同学接口变化时,只需要口头上通知一下即可,我们没有文档,我们很敏捷啊。没错,我们需要承认这样配合开发的效率会很高,但是频繁的变动会导致不断返工,造成了另一种浪费,这种浪费是可以被减少,甚至是被消除的。

为什么接口文档永远都是不对的?

  接口文档在定接口时起到一定作用,写完接口就没有用了。后面接口的频繁变化,文档必定会永远落后于实际接口,维护文档的带来了一定的成本却没能带来价值。除非对外提供的接口,否则文档谁来看呢?没人看,用处又在哪?

  有些公司干脆丢掉接口文档,说我们要拥抱敏捷。

  所以接口文档落后的原因在于没有给我们带来价值

为什么测试工作永远只能临近上线才能开始?

  一个需求,后端开发 4 天,前端开发 4 天,联调 4 天,留给测试同学只有2天时间甚至更少,测不完只能带 bug 上线。

现有开发流程

  在开发阶段测试同学无法介入,接口在变,前端也在变, “提测” 之前只能喝茶,“提测” 之后又忙的要命。

  自动化?想都别想,空有一身好本领,在 “拥抱变化” 之后只能手工测试。偶尔还要拉上前台美眉客串一下测试小妹。手工测试枯燥乏味,乏味的工作就容易出错,而且还不能快速重复,无法对测试过的功能快速回归。

怎么破?

  解决以上问题要让接口文档发挥价值,提高变动接口的成本,测试尽早介入。

  接口文档发挥出价值,就要赋予契约的意义,就如同签字画押谁也不许变,来约束我们只认契约不认人。

  契约应该由前端同学来驱动,前后端共同协商。由于前端同学与 UX 接触比较紧密,更了解页面所需的数据以及整体的 User Journey,前端同学驱动会更加合理。

  契约敲定之后要帮助我们生成 Mock Server(后面我们会介绍一个工具),前后端同学就要依照契约各自开发。Mock Server 可暂时替代后台服务,帮组前端开发,同时,测试同学也可以依照契约文档来编写测试脚本,使用 Mock Server 进行脚本验证。

改进后的开发流程

  当后端接口发生变化除了口头通知以外必须修改契约,前端同学和测试同学才能各自修改。如此一来修改契约的成本变高,人们在定契约时则会更加慎重,也会促使我们提高接口的设计能力。

  看到图中没有 “联调” 的环节,并不是画错了,而是 “联调“ 不再是一项工作,在部署后只需要更改代理的配置即可。甚至使用现代前端框架(如,Vue 或者 React)只要在开发时配置一下,之后都不需要调整任何代码。

  “提测” 呢?测试一直都在进行,也就不再有一个 ”提测“ 的环节,无论前后端任意一方完成开发,测试同学都可以进行测试。

  理论终于扯完了,说起来容易做起来难啊,需要工具来帮助我们。接口描述的工具有很多,比较知名的 SwaggerRaml,我个人更倾向于 Raml 。

API 文档

  描述工具生成文档还不够,还要生成 Mock Server,如果描述工具和 Mock Server 是分离又带来了额外的工作,好在有她——raml-mocker

raml-mocker

  raml-mocker (https://github.com/xbl/raml-mocker) 是一个基于 Raml 使用 Nodejs 开发的 Mock Server 工具,使用 Raml 描述接口中设置 response 的 example 指令即可,raml-mocker 会解析 Raml 文件,并启动一个 Mock Server,将 example 的内容返回给浏览器。

开始

初始化项目

git clone https://github.com/xbl/raml-mocker-starter.git raml-api
cd raml-api
git remote rm origin

安装

yarn
# or
npm install

启动 mock server

yarn start
# or
npm start

测试

curl -i http://localhost:3000/api/v1/users/1/books/
# or
curl -i http://localhost:3000/api/v1/users/1/books/1

生成 API 可视化文档

yarn run build
# or
npm run build

此功能使用了raml2html

配置 .raml-config.json

{
  "controller": "./controller",
  "raml": "./raml",
  "main": "api.raml",
  "port": 3000,
  "plugins": []
}
  • controller: controller 目录路径,在高级篇中会有更详细说明
  • raml: raml 文件目录
  • main: raml 目录下的入口文件
  • port: mock server 服务端口号
  • plugins: 插件

入门篇:Mock Server

raml-mocker 只需要在response 添加 example:

/books:
  /:id:
    post:
      body:
        application/json:
          type: abc
      responses:
        200:
          body:
            application/json:
              type: song
              # 返回的 Mock 数据
              example: !include ./books_200.json

books_200.json

{
  "code": 200,
  "data": [
    {
      "id": 1,
      "title": "books title",
      "description": "books desccription1"
    },
    {
      "id": 2,
      "title": "books title",
      "description": "books desccription2"
    }
  ]
}

通过 curl 请求:

curl -i http://localhost:3000/api/v1/users/1/books

就会得到 example 的数据,唯一不足是无法根据参数动态返回不同数据。别急,请往下看。

高级篇:动态 Server

如果静态的 Mock 数据不能满足你的需求,Raml-mocker 还提供了动态的功能。

在 raml 文档中添加 (controller) 指令,即可添加动态的 Server,如:

/books:
  type:
    resourceList:
  get:
    description: 获取用户的书籍
    (controller): user#getBook
    responses:
      200:
        body:
          type: song[]
          example: !include ./books_200.json

在文档中 (controller) 表示 controller 目录下 user.js 中 getBook 函数。

controller/user.js

exports.getBook = (req, res, webApi) => {
  console.log(webApi);
  res.send('Hello World!');
}

Raml-mocker 是在 expressjs 基础上进行开发,req、res 可以参考 express 文档。

webApi 会返回文档中的配置:

{
  "absoluteUri": "/api/:version/users/:user_id/books",
  "method": "get",
  "controller": "user#getBook",
  "responses": [
    {
      "code": "200",
      "body": "... example ...",
      "mimeType": "application/json"
    }
  ]
}

如此,raml-mocker 提供了更多可扩展空间,我们甚至可以在 controller 中实现一定的逻辑。

插件

Raml-mocker 提供了插件机制,允许我们在不使用 controller 指令的时候对 response 的内容进行处理,例如使用 Mockjs

.raml-config.json

{
  "controller": "./controller",
  "raml": "./raml",
  "main": "api.raml",
  "port": 3000,
  "plugins": ["./plugins/mock.js"]
}

./plugins/mock.js

var { mock } = require('mockjs');

module.exports = (body) => {
  try {
    return mock(JSON.parse(body));
  } catch(e) {}
  return body;
}

Enjoy it!

总结

  前后端分离可以让我们的职责更清晰,打破前端发挥的局限,工作解耦之后能更好的提高开发效率。然而因为没有规划好开发流程,导致了我们没有发挥出其应有的价值,造成了更多的浪费。

  raml-mocker 能够帮助我们在工具上解决一定的问题,更重要的是持续改进的思想,只有团队的思想是统一的才有可能达到快速交付。

  希望能对你有所帮助,谢谢!

简书地址:https://www.jianshu.com/p/941825521354

© 著作权归作者所有

共有 人打赏支持
谢小呆
粉丝 33
博文 4
码字总数 7386
作品 0
朝阳
其他
私信 提问
加载中

评论(47)

谢小呆
谢小呆

引用来自“issumao”的评论

😘首先点赞一下,前后端分离的难点主要在是否大家依照条约去做,或者是否有专门的人进行接口维护和测试,这取决于团队的工作模式,有些团队有这个心,但是在实施的时候,经常变动,或者不进行维护,那么,反而就是一道累赘。随便问下,笔主的图,是用啥子工具做的咧?😏
keynote
issumao
issumao
😘首先点赞一下,前后端分离的难点主要在是否大家依照条约去做,或者是否有专门的人进行接口维护和测试,这取决于团队的工作模式,有些团队有这个心,但是在实施的时候,经常变动,或者不进行维护,那么,反而就是一道累赘。随便问下,笔主的图,是用啥子工具做的咧?😏
-虎口脱险-
-虎口脱险-

引用来自“yywww”的评论

这种东西挺多的呀,阿里系的产品了解一下 https://github.com/thx/RAP

这个也可以了解一下,号称中国最大的API管理平台 https://github.com/eolinker/eoLinker-AMS-Lite-For-Java

丁香园也出过一个,地址找不到了

引用来自“谢小呆”的评论

主要是思路,工具是其次。

工具的确有不少,你提到的这两款刚好是 saas 平台,所以想多聊几句。

saas 有 2 个问题:
一是没办法版本管理,不方便查看历史和回滚(或许有的支持,我不太清楚)。
二是强依赖于外部网络和服务,封闭式开发或者是网络环境不好的时候会反而会阻碍开发速度。

当然,这类开源的工具也是支持在本地部署,只是部署成本并不低,同时也增加了维护成本。

并不是说它们就不好,它们都是非常优秀的工具,主要是看是否适合自己。
saas 有 2 个问题:
一是没办法版本管理,不方便查看历史和回滚(或许有的支持,我不太清楚)。
二是强依赖于外部网络和服务,封闭式开发或者是网络环境不好的时候会反而会阻碍开发速度。

不知道你提的这两个问题算哪门子问题?
谢小呆
谢小呆

引用来自“yywww”的评论

这种东西挺多的呀,阿里系的产品了解一下 https://github.com/thx/RAP

这个也可以了解一下,号称中国最大的API管理平台 https://github.com/eolinker/eoLinker-AMS-Lite-For-Java

丁香园也出过一个,地址找不到了
主要是思路,工具是其次。

工具的确有不少,你提到的这两款刚好是 saas 平台,所以想多聊几句。

saas 有 2 个问题:
一是没办法版本管理,不方便查看历史和回滚(或许有的支持,我不太清楚)。
二是强依赖于外部网络和服务,封闭式开发或者是网络环境不好的时候会反而会阻碍开发速度。

当然,这类开源的工具也是支持在本地部署,只是部署成本并不低,同时也增加了维护成本。

并不是说它们就不好,它们都是非常优秀的工具,主要是看是否适合自己。
yywww
yywww
这种东西挺多的呀,阿里系的产品了解一下 https://github.com/thx/RAP

这个也可以了解一下,号称中国最大的API管理平台 https://github.com/eolinker/eoLinker-AMS-Lite-For-Java

丁香园也出过一个,地址找不到了
风里的叶子
风里的叶子
https://gitee.com/treeleaf/xDoc 基于java源码注释生成在线/离线接口文档, 包含在线测试等功能, 了解一些呗, 让写注释成为一种规范,已经让接口文档真的实时更新
孤独的探索号
孤独的探索号

引用来自“CornWu”的评论

https://gitee.com/CornWu/ApiPluginsFramework
了解一下,使用插件式开发,API在注解的时候把接口契约声明清楚,框架自动生成SWAGGER文档,可以在线直接查看接口参数并测试。

引用来自“谢小呆”的评论

哈哈,终于有人提到在代码中写注解的方式,类似的工具有很多,像 http://apidocjs.com/,swagger 等等。

这虽然看似可以降低文档的维护成本,但仍然是反模式。一方面污染了我们的代码,掺杂了很多与代码无关的东西。另一方面只要与代码无关,代码的调整未必会修改注解,而且也没有报错之类的警告。这看起来好像是在鸡蛋里挑骨头,其实看看我们的代码就知道,有哪些代码已经调整,而注释仍然是错的,错误的注释给我们带来的困扰比没有注释更大。

为什么说它是反模式呢?
原因在于仍然是在 “等” 后端同学将代码写出来,才生成文档。除非这就是我们定的契约方式,但修改契约就固定成了后端同学。如此一来,原本可以大家一起维护的就变成一个角色的工作。

感谢您的回复,我没有仔细了解此框架,所以如果言语有不当之处先说声抱歉。回复的目的不在于攻击,而是通过讨论产生更多思考。

引用来自“CornWu”的评论

确实会出现你所说的,但是想一下,平时编写API的时候,都会写入口和出口参数的注释,那么我们何不利用这个注释来变成我们的接口契约呢?其实前端的同学也不需要等待后端的同学把代码写好了才能写前端,可以使用暂时去掉前后端交互的那个流程,先暂时用假数据代替。
APIJSON 提供了完全自动化的 API,
自动将 JSON 转为 SQL 执行并返回 JSON 结果,
期间自动校验权限、参数、结构,
所以后端不用写代码就能提供接口,
再也不用假数据模拟了。

https://github.com/TommyLemon/APIJSON
孤独的探索号
孤独的探索号

引用来自“CornWu”的评论

https://gitee.com/CornWu/ApiPluginsFramework
了解一下,使用插件式开发,API在注解的时候把接口契约声明清楚,框架自动生成SWAGGER文档,可以在线直接查看接口参数并测试。

引用来自“谢小呆”的评论

哈哈,终于有人提到在代码中写注解的方式,类似的工具有很多,像 http://apidocjs.com/,swagger 等等。

这虽然看似可以降低文档的维护成本,但仍然是反模式。一方面污染了我们的代码,掺杂了很多与代码无关的东西。另一方面只要与代码无关,代码的调整未必会修改注解,而且也没有报错之类的警告。这看起来好像是在鸡蛋里挑骨头,其实看看我们的代码就知道,有哪些代码已经调整,而注释仍然是错的,错误的注释给我们带来的困扰比没有注释更大。

为什么说它是反模式呢?
原因在于仍然是在 “等” 后端同学将代码写出来,才生成文档。除非这就是我们定的契约方式,但修改契约就固定成了后端同学。如此一来,原本可以大家一起维护的就变成一个角色的工作。

感谢您的回复,我没有仔细了解此框架,所以如果言语有不当之处先说声抱歉。回复的目的不在于攻击,而是通过讨论产生更多思考。
所以就有了 APIJSON ,自动化的 API 是直接对接数据库的, 数据库表和字段属性就能当文档用了。

后端接口和文档自动化,前端(客户端) 定制返回JSON的数据和结构!
https://github.com/TommyLemon/APIJSON
CornWu
CornWu

引用来自“CornWu”的评论

https://gitee.com/CornWu/ApiPluginsFramework
了解一下,使用插件式开发,API在注解的时候把接口契约声明清楚,框架自动生成SWAGGER文档,可以在线直接查看接口参数并测试。

引用来自“谢小呆”的评论

哈哈,终于有人提到在代码中写注解的方式,类似的工具有很多,像 http://apidocjs.com/,swagger 等等。

这虽然看似可以降低文档的维护成本,但仍然是反模式。一方面污染了我们的代码,掺杂了很多与代码无关的东西。另一方面只要与代码无关,代码的调整未必会修改注解,而且也没有报错之类的警告。这看起来好像是在鸡蛋里挑骨头,其实看看我们的代码就知道,有哪些代码已经调整,而注释仍然是错的,错误的注释给我们带来的困扰比没有注释更大。

为什么说它是反模式呢?
原因在于仍然是在 “等” 后端同学将代码写出来,才生成文档。除非这就是我们定的契约方式,但修改契约就固定成了后端同学。如此一来,原本可以大家一起维护的就变成一个角色的工作。

感谢您的回复,我没有仔细了解此框架,所以如果言语有不当之处先说声抱歉。回复的目的不在于攻击,而是通过讨论产生更多思考。
框架里,我已经做了参数校验的功能,前台传过来的参数如果和注解里的参数不一致的时候,会报错,不会调度到对应的API上。
CornWu
CornWu

引用来自“CornWu”的评论

https://gitee.com/CornWu/ApiPluginsFramework
了解一下,使用插件式开发,API在注解的时候把接口契约声明清楚,框架自动生成SWAGGER文档,可以在线直接查看接口参数并测试。

引用来自“谢小呆”的评论

哈哈,终于有人提到在代码中写注解的方式,类似的工具有很多,像 http://apidocjs.com/,swagger 等等。

这虽然看似可以降低文档的维护成本,但仍然是反模式。一方面污染了我们的代码,掺杂了很多与代码无关的东西。另一方面只要与代码无关,代码的调整未必会修改注解,而且也没有报错之类的警告。这看起来好像是在鸡蛋里挑骨头,其实看看我们的代码就知道,有哪些代码已经调整,而注释仍然是错的,错误的注释给我们带来的困扰比没有注释更大。

为什么说它是反模式呢?
原因在于仍然是在 “等” 后端同学将代码写出来,才生成文档。除非这就是我们定的契约方式,但修改契约就固定成了后端同学。如此一来,原本可以大家一起维护的就变成一个角色的工作。

感谢您的回复,我没有仔细了解此框架,所以如果言语有不当之处先说声抱歉。回复的目的不在于攻击,而是通过讨论产生更多思考。
确实会出现你所说的,但是想一下,平时编写API的时候,都会写入口和出口参数的注释,那么我们何不利用这个注释来变成我们的接口契约呢?其实前端的同学也不需要等待后端的同学把代码写好了才能写前端,可以使用暂时去掉前后端交互的那个流程,先暂时用假数据代替。
前后端分离-为什么分离

What? 什么是前后端分离?一般我们所说的前后端分离都是说开发模式的前后端分离,部署一般也是分离的。 现在我所知道的常见的开发模式有: 传统的MCV模式:前端写html,后端套界面,转成jsp...

郭恩洲_OSC博客
2016/11/21
25
0
基于NodeJS的全栈式开发

随着不同终端(Pad/Mobile/PC)的兴起,对开发人员的要求越来越高,纯浏览器端的响应式已经不能满足用户体验的高要求,我们往往需要针对不同的终端开发定制的版本。为了提升开发效率,前后端分...

唐僧他大叔
2015/02/21
0
0
前后端分离方案交流,大家发表一下看法

基于NodeJS的前后端分离(此文章来自淘宝) 前言 为了解决传统Web开发模式带来的各种问题,我们进行了许多尝试,但由于前/后端的物理鸿沟,尝试的方案都大同小异。痛定思痛,今天我们重新思考...

Koala_考拉
2014/05/26
9.7K
13
前后端分离的思考与实践(一)

原文出处:淘宝UED - 常胤 也谈基于NodeJS的全栈式开发(基于NodeJS的前后端分离) 前言 为了解决传统Web开发模式带来的各种问题,我们进行了许多尝试,但由于前/后端的物理鸿沟,尝试的方案...

淘宝UED - 常胤
2014/04/18
0
0
前后端分离,最佳实践

文章目录 1.前后端分离是什么 2.为什么需要前后端分离 3.前后端分离,最佳实践 3.1.简单分离模式 3.2.服务端渲染模式 3.2.1.方式一,JSP渲染 3.2.2.方式二,静态页渲染 3.3.Node.js渲染模式 ...

郭恩洲_OSC博客
2016/11/21
30
0

没有更多内容

加载失败,请刷新页面

加载更多

领哥,项目管理

领哥 https://www.leangoo.com/kanban/board_list

miaojiangmin
14分钟前
1
0
2018阿里云双12年终大促主会场全攻略

摘要: 双12官方攻略出炉! 2018阿里云双12年终大促活动已经于12月7日正式开启,从已开放的活动页面来看,活动分为两个阶段: 12月7日-12月23日的拉新返现阶段和12月24日-12月28日的TOP100英...

阿里云云栖社区
15分钟前
1
0
努力使失败保持原子性(64)

失败的原子调用应该使得对象保持在被调用之前的状态,所谓:失败原子性 几种途径实现: 设计一个不可变对象,其失败原子性是显然的 对于可变参数,执行前检查参数有效性 避免执行一半报错,后...

Java搬砖工程师
15分钟前
1
0
slot分发内容

slot元素作为组件模板之中的内容分发插槽。这个元素自身将被替换。 有 name 特性的 slot 称为具名 slot。 有 slot 特性的内容将分发到名字相匹配的具名 slot。 内容分发就是指混合父组件的内...

Carbenson
27分钟前
1
0
python开发入门

1.执行python文件 # python ./demo.py 2.Python ImportError: No module named 'requests'异常 解决方法: # pip install requests;...

硅谷课堂
28分钟前
2
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部