API设计规范

设计前必读

整体规范建议使用 RESTful 风格

• API 设计人员需要熟悉前端业务逻辑
• API 文档使用自动化工具生成，提升后台开发效率（Swagger）

版本控制

应该将API的版本号放入URL，如 https://api.example.com/v{n}/，采用多版本并存，增量发布的方式。

请求方式

对于资源的具体操作类型，由 HTTP 动词表示，常用的 HTTP 动词有下面四个（括号里是对应的SQL命令）：

• GET (SELECT): 从服务器取出资源（一项或多项）
• POST (CREATE): 在服务器新建一个资源，或者更新单个资源
• PUT (UPDATE): 在服务器更新资源（客户端提供改变后的完整资源）
• DELETE (DELETE): 从服务器删除资源

返回字段

命名规范

• 前后端约定统一使用小写字母命名的驼峰法（eg：channelName）
• 时间格式统一使用13位毫秒格式的时间戳（eg:1481615628000）
• Boolean类型统一使用 int值类代替（eg: 1 > true; 0 > false）

字段类型

对于实体的字段，应当严格按照字段的含义来决定类型，尽量避免“使用逗号分割的字符串表示数组”之类的情况发生。

推荐方式：

[
    {
        "tag": "<!--IMG#0-->",
        "width": 500,
        "height": 362,
        "originalPath": "100/20160531/a09287f205e24df387812ff29171e1ef_0.jpg",
        "thumbnail": "50/20160531/a09287f205e24df387812ff29171e1ef_0.jpg"
    }
]

不推荐使用下面方式：

{
    "originalPath": "[{"tag":"\u003c!--IMG#0--\u003e","width":500,"height":362,"originalPath":"100/20160531/a09287f205e24df387812ff29171e1ef_0.jpg","thumbnail":"50/20160531/a09287f205e24df387812ff29171e1ef_0.jpg"}]"
}

良好的格式有助于对数据的进一步解析和格式化输出，可以避免不少分隔字符串、转换为文本、拼接字符串的操作等格外工作。

空值处理

客户端异常、崩溃很多情况是因为空指针导致的，处理空值显得尤为重要

• 基本数据类型设置默认值（eg：int：0 float：0.00000000）
• 字符串赋值""
• 字典对象赋值{}
• 数组赋值[]

JSON示例

{
    "total_number": 0,
    "message": "",
    "data": [],
    "tips": {}
}

返回模板

为了保障前后端的数据交互的顺畅，规范数据的返回，并采用固定的数据格式封装。

{
    "status" : 200,
    "data" : {}, // "" ， 0 ，[]，
    "message" : "成功"
}

status
接口的执行的状态。200表示成功，其他表示异常。只要 API 接口成功接到请求，就不能返回 200 以外的 HTTP 状态码。

data
接口的主数据，以根据实际返回数组或JSON对象。

message
当 status != 200时，都应该有对应的错误信息。