前后端接口规范---关键点1

关于REST

前后端接口按照粗浅的REST规则制定，其主要表现为：

使用GET、POST、PUT、DELETE共4个HTTP Method，而非简单的GET和POST两者。
响应使用HTTP状态码来标志请求的执行结果，而非以往的success字段。
URL符合业界普遍接受的REST规则，减少在URL中标识操作类型的情况，如使用POST /users代替POST /users/save。

出于技术的限制，对于一些特殊的场景，接口会在REST设计的基础之上进行一些妥协，具体参考各接口规范说明。

在REST接口规范中，URL符合以下约束：

实体名称均以复数形式表示，如GET /users或POST /users/status。
URL最后 不得 添加斜杠/符号。
对于GET请求，数据在URL后通过标准的query格式提供，如GET /users?status=1,2&keyword=hello。
对于各系统，可以在URL前统一添加固定的前缀，如GET /api/{entities}/{id}，前缀应尽量固定。可以根据请求的类型（如是否需要用户登录授权等）使用不同的前缀。规范推荐按以下规则使用前缀：
如果是需要登录授权的接口，以/api/js为前缀。
其它接口，通常没有权限控制，以/api/tool为前缀。

关于数据类型

请求可以使用以下两类数据类型，由具体的项目及接口根据实际情况决定：

表单编码格式。此格式为简单的a=b&c=d这一形式，使用此请求格式时，请求的Content-Type头的值必须为application/x-www-form-urlencoded。
JSON格式。此格式为一个完整的符合JSON格式的串，使用此请求格式时，请求的Content-Type头的值必须为application/json。

响应可以使用以下几类数据类型：

JSON格式。多数接口应当使用JSON格式的响应，此时响应的Content-Type头的值必须为application/json。
HTML格式。部分接口，如文件上传，由于技术的限制必须使用<iframe>元素完成，返回的响应为一个HTML片段，此时响应的Content-Type头的值必须为text/html，且响应状态码必须为200，具体可参考下文的文件上传相关接口规范。
JSONP格式。当跨系统调用API时，会需要使用JSONP接口，此时响应的Content-Type头的值必须为application/x-javascript，使用请求的URL中的callback字段的值为函数名返回相应的JSONP片段。

关于编码

所有请求和响应均 必须 使用utf-8为编码。此标准体现在请求和响应的Content-Type头的值后必须配有;charset=utf-8字样。

对于前端使用JSONP的场景，则应当为<script>标签添加charset="utf-8"属性。
关于CSRF

系统必须对CSRF（客户端伪造请求）具有防御能力，因此在系统中，必须加上CSRF Token。

CSRF Token在用户登录后，第一次加载用户信息时，由后端提供，其值为一个任意字符串。

CSRF Token应当被应用在所有对数据有影响的接口中，包括所有的POST、PUT和DELETE请求；对于GET请求由于通常不影响数据，不会造成破坏性的后果，建议不使用CSRF Token。

在需要CSRF Token的每一个AJAX请求中，客户端必须添加名为X-Session-Token的请求头，其值为后端提供的CSRF Token。如果不提供X-Session-Token请求头，则后端应当返回400状态码。

对于非AJAX的请求，如文件上传，则应当在POST请求的表单中添加sessionToken字段，其值为后端给出的CSRF Token。

根据业务的需要和技术的限制，后端可对部分接口添加白名单，以使接口不需要CSRF Token即可请求，这通常用于获取当前用户信息前就必须请求的接口，由于此时前端不能获取CSRF Token，因此此类接口必须在白名单中，以确保系统可用。
关于超时

系统的AJAX请求必须配有超时时间，具体时间可根据系统部署环境、网络状况、请求响应大小等因素决定，标准给出的参考值为15秒。
关于缓存

REST设计的一个原则为有效利用缓存，因此接口的设计 必须 将缓存作为一个因素，进行认真的设计并写入接口文档。

所有POST、PUT和DELETE请求均不缓存，这一点由浏览器自身保证，无需额外的配置。

对于GET请求，必须合理地配置缓存头，标准建议使用以下方式实现缓存：

如果资源是实时变化无法缓存的，则请求时带时间戳字段，时间戳字段的参数名为_，后端应当忽略此字段。同时无缓存的GET请求，响应中应当有Cache-Control: no-cache头，且 不得 含有ETag和Last-Modified头，如果包含Expires头，则其值必须为一个过去的时间。
如果资源带有最后修改时间（如数据库中有last_update_time列），则建议将此时间作为响应的Last-Modified头返回，前端 不对 该请求添加时间戳，以实现正确的缓存。当可以生成Last-Modified头时，不建议同时生成ETag头。
如果资源带有一个唯一的版本标识（如数据库中有rowid列），则建议将此标识值作为响应的ETag头返回，前端 不对 该请求添加时间戳，以实现正确的缓存。当可以生成ETag头时，不建议同时生成Last-Modified头，两者以Last-Modified头为优先。
如果一个资源可以有假定的缓存时间，则通过Cache-Control: max-age={seconds}或Expires响应头进行配置。标准建议使用此类缓存时慎重考虑，在请求不是系统性能瓶颈时，不建议使用此类缓存。

关于接口文档

接口文档应当 至少 包含以下内容：

接口的名称及简单的作用描述。
接口的URL和请求时使用的HTTP Method。
接口的请求格式及参数。
接口可能返回的状态码，及每个状态码下的响应类型和格式。
接口的缓存设计。

以下为一个典型的接口文档：

## 用户列表

用于获取用户列表，带分页功能

## 接口：

GET /users

## 请求参数：

| 名称     | 类型   | 定义        | 必需 | 默认值 | 说明
| keyword | string | 查询关键词   |     | ""    | 作用于name和id字段
| page    | number | 页码        |     | 1     |
| role    | number | 角色        |     | 全部   | 参考角色枚举说明
| orderBy | string | 排序字段名称 |     | "id"   | 可以使用"id"或"name"
| order   | string | 排序方式     |    | "asc"  | 可以为"asc"或"desc"

## 响应：

### 成功：200

响应格式：JSON

{
totalCount: {number}, // 总数
results: [
{
"id": {number},
"name": {string},
"role": [{number}, ...], // 角色，多个角色用数组表示
"birthday": {string}, // 生日使用YYYYMMDD格式
},
...
]
}

缓存配置：使用`ETag`进行缓存。

### 参数不合法：409

参考标准409响应

在文档中，对于一些整个项目统一的内容，如页码默认值为1之类，可以省略说明，在单独的总体设计文档中标注即可。