前后端交互规范

工作流程优化
Requests（请求）
Responses（响应）

工作流程优化

产品研发过程中，"前后端分离"开发模式下的前后端协同开发流程优化如下：

前后端协同开发流程较之前不同的是，添加了 “接口评审” 过程，此过程是对程序设计产物 接口文档 及接口的评审及确认，旨在解决实践中遇到的以下问题：

无接口文档，口述沟通
接口功能不完善就提前进入联调
接口功能拆分的维度不合理
接口功能测试依赖前端界面
接口格式规范存在多种：WCF Server（.svc）和 Web API
接口请求方式无语义
...

Requests（请求）

1、语义化请求的方式

在 RESTful 架构中，对于资源的具体操作类型，由 HTTP 动词表示。常用的 HTTP 动词有（括号里是对应的SQL命令）：

POST（CREATE）：在服务器新建一个资源。

DELETE（DELETE）：从服务器删除资源。

PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。

PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。

GET（SELECT）：从服务器取出资源（一项或多项）。

HEAD：获取资源的元数据。

OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

axios({
    url: '/api/v1/users',
    method: 'GET',
    ...
})
...

2、应该将 API 的版本号放入 URL

需求迭代过程中，接口难免会发生调整，给接口加上版本使之更易于维护。

https://api.example.com/api/v1/

3、路径和属性要小写

为了和域名命名规则保持一致，使用小写字母并用 - （中杠）分割路径名字，例如：

service-api.com/users
service-api.com/app-setups

属性也使用小写字母，但是属性名要用 _（下划线）分割，以便在 JavaScript 中省略引号。例如：

{
    "service_class": "first"
}

针对 C# 项目，属性的命名规范，可采用驼峰形式（如果可能，建议使用上面的方式）：

{
    "serviceClass": "first"
}

注意：同一个项目，属性的命名规范，只能采用一种。

4、通常情况下，请求的 body 体使用 JSON 数据格式

通常情况下，服务端接收到的数据格式为 JSON 字符串。

// 通常：
// Content-Type: application/json
axios({
    data: JSON.stringify({...}),
    ...
})
...

// 特殊：表单提交
// Content-Type: application/x-www-form-urlencoded

// 特殊：文件上传
// Content-Type: multipart/form-data

Responses（响应）

1、使用 JSON 作为数据传输格式

服务端返回的数据格式，应该只使用 JSON，避免使用 XML。

2、保证响应的 JSON 最小化

只返回业务所需的资源；
请求中多余的空格会增加响应大小，应去掉；
开启压缩模式；

3、返回合适的 HTTP 状态码和业务返回码

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。

201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。

202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）

204 NO CONTENT - [DELETE]：用户删除数据成功。

400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。

401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。

403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。

404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。

406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。

410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。

422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。

500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

业务码的设计需是全局唯一的，可参考微信公众平台的接口返回码说明。

4、提供资源的（UU）ID

在默认情况给每个资源一个 id 属性。除非有更好的理由，否则请使用 UUID。不要使用那种在服务器上或资源中不是全局唯一的标识，尤其是自动增长的 id。

生成小写的 UUID 格式 `8-4-4-4-12`，例如：

[{
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    ...
}, {
    "id": "01234567-89ab-cdef-0123-456789abcdef",
    ...
}]

5、使用 UTC（世界标准时间）时间，用 ISO8601 进行格式化

仅接受和返回 UTC 格式的时间，IOS8601 格式的数据，例如：

{
    "finished_at": "2012-01-01T12:00:00Z"
}

前后端交互规范