请求与响应格式规范探讨（一）某次前端周会时讨论过三个问题。一是代码风格的问题，二是与后端对接时接口的问题，三是监控的

0、背景

概述

某次前端周会时讨论过三个问题。

一是代码风格的问题，二是与后端对接时接口的问题，三是监控的问题。

代码风格上，我们希望整个项目看上去大体的风格是统一的,但是又希望每个人都有自由发挥的空间。
而在与后端对接的接口上，我们希望：
- 不无限制地增加新接口
- 接口数据格式统一，不需要前端去做（增加）额外的“抹平”。
监控方面，目前上报的jsError很多，但真正有用的很少，且同一自定类别的上报信息中混杂着多种错误信息，难以分类。

因此，本文为对发出请求到响应请求过程中的部分问题的探讨思考，希望能对解决上述问题提供帮助。

目标

梳理代码层面从发出请求到响应请求的整个流程，探讨各步骤可行的（改进）方案，推进实现以下目标：

统一项目的大体风格，降低接手理解难度；
确认接口数据格式规范，减少修改公共代码的“需求”；
限制接口数量膨胀速度；
将网络错误与业务错误隔离，方便错误分类统计。

方案

引入 RESTful 风格
探讨、约定请求及响应的参数格式
对请求和响应进行拦截/代理加工

1、接口URL设计

可选风格

文件路径式。一个路径对应一个资源。
MVC。根据URL找到对应的控制器和行为；行为调用相关的模型，进行数据操作；数据操作结束后，调用视图和相关数据进行页面渲染，输出到客户端。
1. 手工映射。手动配置URL对应的逻辑（控制器）。可以通过正则来匹配路径和解析参数。
2. 自然映射。将路径部分也当成参数来处理解析。
RESTful （(Resources) Representation State Transfer）。
1. 在MVC的基础上，加入了HTTP方法。URI中不带动词，全部是名词。基础动作通过post、get、put、patch、delete来区分。

对比：

风格	直观程度	灵活性	需要定义的接口数量
文件路径式	高	低	高
MVC	中	高	中
RESTful	中	高	低

现状：

主要使用的还是MVC手工映射的方式。可引入RESTful。引入的影响：

接口数量减少，更易于维护。
可能需要通过post来模拟delete、put、patch
其他待掘友补充

2、请求相关问题

请求参数

什么时候传字符串，什么时候传对象、数组？

之前碰到过要求将某一个参数值（对象类型）转换成字符串后，再和其他参数一起传给后端。这种情况下怎么处理比较好呢？

日期形式？

不同语言前台和后台获取到的date格式不同，而时间戳都是一样的，所以统一传时间戳是个不错的选择。

更新时是否只传更新的内容（除id之类关键字段外）？

一般情况只传更新的内容更好。
特殊情况就是嵌套较多、较深时，只取更新的内容比较麻烦。应尽量避免这种情况。

请求拦截/代理

统一添加 host （部分项目中由于同一环境下有多个不同的域名，因此无法统一添加host）

添加公共参数

错误处理

错误上报信息?
是否重发？
取消遮罩

loading遮罩

默认不加。
在需要禁止用户操作时添加
表格数据加载时，仅加 loading 动画，不加遮罩

3、响应相关问题

状态码

GET: 200 OK
POST: 201 Created
PUT: 200 OK
PATCH: 200 OK
DELETE: 204 No Content
。。。

目前的情况是，只要接口是通的，即使请求失败了（业务错误），返回的状态码都是200。个人比较赞同当前方案。

响应参数

目前各业务需求不同，参数风格也不统一（尤其是在接手其他团队的业务时），发展到现在也很难统一。

推荐基础格式：

参数	参数名称	是否必填	参数类型	参数说明
status	请求结果状态	是	Integer	成功、失败、未登录等
error	错误信息	否	Object / String	错误信息复杂时，为Object
data	业务数据	否	Object	仅当status返回的状态码表示成功时必填
其他	业务数据	否	基础数据类型	当有两条以上数据时，请使用data

表格数据：

无数据时传空数组，若有翻页，则同时返回total为0

响应拦截/代理

隐藏 loading动画及遮罩

对不同的数据格式进行抹平