位置、格式
请求参数
| HTTP方法 | 位置 | 格式 | ContentType |
|---|---|---|---|
| GET | URL | 字符串 | 无 |
| POST | 请求体 | JSON | application/json |
| PUT | 请求体 | JSON | application/json |
| DELETE | 请求体 | JSON | application/json |
返回参数
| HTTP方法 | 位置 | 格式 |
|---|---|---|
| GET | 响应体 | JSON |
| POST | 响应体 | JSON |
| PUT | 响应体 | JSON |
| DELETE | 响应体 | JSON |
信息存储
key 仅起引导、定位信息的作用，不保存有效信息
// bad
"list": [
{"66": "Tony"}
]
// good
"list": [
{"id": "66", "name": "Tony"}
]
格式
请求参数、返回参数的数据结构，都应该遵守如下规则：
- 某个资源字段
<2时，要求结构：扁平化 - 某个资源的字段
>=2时，要求结构：非扁平化，面向对象的树形结构 - 字段职责明确、语义化
// 请求
// bad
{
"user": {
"name": "Tony"
}
}
// good
{
"name_user": "Tony"
}
// 返回
// bad
"list": [
{
"type_search": 1,
"id_user": 66,
"name_user": "Tony",
"sex_user": 1
}
]
// good
"list": [
{
"type_search": 1,
"user": {
"id": 66,
"name": "Tony",
"sex": 1
}
}
]
返回参数格式
| 顶级属性 | 作用 |
|---|---|
| data | 目的数据 |
| err | 一级数据状态码 |
| msg | 详细状态信息，包含二级数据状态码、具体描述等 |
- 成功响应
{
data: {
// ...
},
err: 0,
msg: null
}
- 失败响应
{
data: null,
err: 1,
msg: {
err: 1001,
// ...
}
}
- 空响应（成功，但数据为空）
{
data: null,
err: 2,
msg: null
}
特殊场景
| 场景 | 方式 |
|---|---|
| 文件上传 | formData |
| 文件下载 | URL |
其他
空白字段
即使可选字段的值为空，也需要传递该字段，参数值为 null，而不是直接省略
若空白字段存在于URL中，拼接字符串时，应该留空参数值。
如：?a=&b=1
无效字段
请求参数中，不能带有无效字段
时间戳
统一使用 ISO 8601 时间戳（附带时区信息）
格式：YYYY-MM-DDTHH:MM:SSZ
参数限制
- 分页范围
- 账号、密码格式
- ...
允许同时控制多个资源
需要申请操作的资源，以数组形式，存放到请求参数中
User-Agent
设置 User-Agent 值为 项目名称，防止无效用户访问
UUID
- 每次请求之前，随机一个UUID，存放到请求头，便于错误追踪
- 在资源唯一标识符上，使用UUID（varchar）代替 自增主键ID（int）
