简述
使用 RESTful API规范统一约束客户端和服务器之间的接口。简化和分离系统架构，使每个模块独立。前后端交互的API,需要明确协议、域名、路径、请求方法、请求内容、状态码、响应体。
建议
- 请求中使用URI定位资源
- 用HTTP Verbs[动词]（GET、POST、PUT、DELETE）描述操作（具体表现形式）
- 数据传递（默认）采用：
Content-Type: application/json; charset=utf-8 - 后端定义前端请求字段要符合小驼峰驼峰命名如：storeName；见名知意；后台返回字段也需符合驼峰命名
- 保障接口文档对应字段应和后端返回一致
- 前后端数据相关的接口返回，如果为空，需返回完整键名
- 前后端数据相关的接口返回，如果为空，则返回空数组[]或空集合{}。
- 建议一个接口对应一个功能
- 服务端发生错误时，返回给前端的响应信息必须包含 HTTP 状态码，errorCode、 errorMessage、用户提示信息四个部分。
- 对于需要使用超大整数的场景，服务端一律使用 String 字符串类型返回，禁止使用 Long 类型。
- HTTP请求通过URL传递参数时，不能超过2048字节
- HTTP 请求通过 body 传递内容时，必须控制长度。(实在超出可调整nginx配置，适当解除限制)
- 前后端的时间格式统一为"yyyy-MM-dd HH:mm:ss"，建议统一为GMT
URL规范
GET https//domain.com/api/{模块名}/{?菜单名}/{接口名}/:param
- 不能使用大写，单词如果要分割，统一使用下划线 _
- 使用名词表示资源集合，推荐使用复数形式
- 禁止携带后缀，比如 .json, .xml，应通过accept头表达
- 无需在URI中增加版本号，如有必要应通过HTTP请求头信息的字段中进行区分
参考示例图：
请求方法
| 请求方法 | 说明 | 安全性 | 幂等性 |
|---|---|---|---|
| GET | 获取资源 | ✔️ | ✔️ |
| POST | 创建资源 | ❌ | ❌ |
| PUT | 替换(新增或完整更新) | ❌ | ✔️ |
| DELETE | 删除资源 | ❌ | ✔️ |
| PATCH | 是对 PUT 方法的补充，用来对已知资源进行局部更新 | ❌ | ✔ |
| OPTIONS | 用于url验证，验证接口服务是否正常 | ✔️ | ✔️ |
| TRACE | 回显服务器收到的请求，主要用于测试或诊断 | ✔️ | ✔️ |
说明：
- 安全性 ：不会改变资源状态，可以理解为只读的；
- 幂等性 ：执行1次和执行N次，对资源状态改变的效果是等价的。
- 查询字段内容过多，统一使用POST方式查询，请求地址增加/query加以区分
- 批量删除，统一使用POST方式，请求地址增加/delete加以区分
由于存在批量删除的情况，而一些网关、代理、防火墙在收到DELETE请求后，会把请求的body直接剥离掉。建议将存在批量删除的接口统一改成POST提交，为了标识是删除操作，在请求路径上增加/delete。
GET
被用于获取资源。不允许对服务器上资源做任何修改操作。
示例：
GET http://www.example.com/customers/12345
GET http://www.example.com/customers/12345/orders
GET http://www.example.com/buckets/sample
PUT
常用于更新资源。通过请求体携带资源发送给服务器。注意： 在资源ID由客户端而不是由服务器选择的情况下，也可以使用PUT来创建资源。修改成功返回200，创建成功返回201。建议使用post进行创建新资源。
示例：
PUT http://www.example.com/customers/12345
PUT http://www.example.com/customers/12345/orders/98765
PUT http://www.example.com/buckets/secret_stuff
POST
常用于创建新资源。创建成功通常返回201。
示例：
POST http://www.example.com/customers
POST http://www.example.com/customers/12345/orders
DELETE
删除资源。
示例：
DELETE http://www.example.com/customers/12345
DELETE http://www.example.com/customers/12345/orders
DELETE http://www.example.com/buckets/sample
应用说明
| HTTP Verb | /customers | /customers/{id} |
|---|---|---|
| GET | 200 (OK)，customers列表。 可用于分页、排序、过滤。 | 200 (OK)，单个customer。如果id不存在或非法，返回404 (NotFound)。 |
| PUT | 404 (Not Found)，除非你想更新整个资源 | 200 (OK) 或者204 (No Content)。如果id不存在或非法，返回404 (NotFound)。 |
| POST | 201 (Created) | 404 (Not Found) |
| DELETE | 404 (Not Found)，除非你想删除整个资源 | 200 (OK) 。如果id不存在或非法，返回404 (NotFound)。 |
状态码
| 状态码 | 说明 |
|---|---|
| 200 OK | 服务器成功返回请求的数据 |
| 201 CREATED | 新建或修改数据成功 |
| 202 Accepted | 表示一个请求已经进入后台排队（异步任务） |
| 204 NO CONTENT | 删除数据成功 |
| 400 INVALID REQUEST | 请求有错误，服务器没有进行新建或修改数据的操作（幂等操作） |
| 401 INVALID REQUEST | 没有权限（令牌、用户名、密码错误） |
| 403 Forbidden | 没有权限（令牌、用户名、密码错误） |
| 404 NOT FOUND | 请求记录不存在，服务器没有进行操作（幂等操作） |
| 406 Not Acceptable | 请求的格式不符合（比如用户请求JSON格式，但是只有XML格式） |
| 500 INTERNAL SERVER ERROR | 服务器发生错误，无法判断发出的请求是否成功 |
子状态码
考虑到更多状态需要传递，建议在返回体中添加子状态码字段
响应体
- 前后端交互字段全部使用小驼峰方式
{
"code": 200, // HTTP响应码
"subCode": "600xxx", // 后端定义的状态码
"status": "success/fail/error",
"content/data": []/{}, // 多条记录使用JSON数组，单条记录使用JSON对象
"errorMessage": [], // 状态为error或fail时，对应的错误信息
"errorTips": [], // 错误提示信息
"page": {
"total": number, //分页总数
"pages": number,
...rest
}
}
排序
使用数组传递排序字段，-表示降序，无任何标识表示升序
sorts: ['-age', 'name']
时间
日期和时间戳如果没有适当和一致地处理，可能是一个真正的头痛。建议使用UTC或GMT时间存储，处理，缓存等时间戳或者使用统一格式化的时间字符串”yyyy-MM-dd HH:mm:ss”
