API 文档编写规范（参数篇）

位置、格式

请求参数

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）