接口路径的设计
路径是指后端提供给前端调用该接口的地址，其实就是该接口的链接，最好以一个较为明显的词为开头，或者说以单独的域开头，路径还要向语义化靠拢，这里只是路径，不涉及到参数，比如：
注：通常是复数时会在词后加s，比如照片是photo，但照片集，多个照片时是photos
- /api/bid/list.htm 产品列表
- /api/bid/get.htm 产品详情
- /api/bid/buy.htm 产品购买
- /api/photos/list.htm 照片列表
- /api/photos/get.htm 图片详情
接口参数的设计
参数分必选和可选，分数据类型，字段说明，如：
| 参数名 | 必选 | 类型及范围 | 说明 |
|---|---|---|---|
| currentPage | false | int | 当前页默认为1 |
| pageSize | false | int | 每页多少条数据, 默认为10 |
| status | true | int | 状态, 1未开始, 2进行中, 3已完成, 4已删除 |
接口文档的设计
- wiki
目前我们采用的管理办法，接口多而乱，搜索查找不方便，编写不够方便。
- 第三方平台
eoLinker接口管理平台，https://www.eolinker.com/#/index
ShowDoc一个非常适合IT团队的在线API文档、技术文档工具 https://www.showdoc.cc
YApi 是一个可本地部署的、打通前后端及QA的、可视化的接口管理平台 https://hellosean1025.github.io/yapi
- swagger
后台代码植入生成
接口数据的设计
接口的数据一般都采用JSON格式进行传输，不过，需要注意的是，JSON的值只有六种数据类型：
- Number：整数或浮点数
- String：字符串
- Boolean：true 或 false
- Array：数组包含在方括号[]中
- Object：对象包含在大括号{}中
- Null：空类型
所以，传输的数据类型不能超过这六种数据类型。
对于Date类型，必须做特殊处理，最好的解决方案是用毫秒数表示日期。
对于空对象也最好不要下传。
另外，不要出现字符串的“true”和”false”，或者字符串的数字，特别字符串的“null”，这样会导致解析错误，尤其是”null”，可能直接导致程序奔溃。
服务器返回的数据结构，一般为：
//成功
{
"code": 0
}
//提交失败
{
"code": 1,
"message": "参数错误"
}
{
"code": 1001,
"message": "未登录"
}
//获取单个数据
{
"code": 0,
"data": {}
}
//获取分页列表
{
"code": 0,
"data": [],
"pageSize":10,
"currentPage":1,
"totalPage":5,
"totalCount":49
}
- code: 状态码，0表示成功，非0表示各种不同的错误
- message: 描述信息，成功时为空，错误时则是错误信息
- data: 成功时返回的数据，类型为对象或数组
code
不同错误需要定义不同的错误码，属于不同客户端的错误和服务端的错误也要区分，比如1XX表示客户端的错误，2XX表示服务端的错误。这里最好采用数字来表示，好处理。
1000以下是系统的状态码（Http状态码）
1000-10000系统中通用的状态码
每个模块状态码以10000递增
如微信错误码：
http://mp.weixin.qq.com/wiki/17/fa4e1434e57290788bde25603fa2fcbd.html
例如：
- 0：成功
- 100：请求错误
- 101：缺少appKey
- 102：缺少签名
- 103：缺少参数
- 200：服务器出错
- 201：服务不可用
- 202：服务器正在重启
message
错误信息一般有两种用途：
- 一是客户端开发人员调试时看具体是什么错误；
- 二是作为App错误提示直接展示给用户看。
主要还是作为App错误提示，直接展示给用户看的。所以，大部分都是简短的提示信息
data
data字段只在请求成功时才会有数据返回的。
数据类型限定为对象或数组，当请求需要的数据为单个对象时则传回对象，当请求需要的数据是列表时，则为某个对象的数组。
这里需要注意的就是，不要将data传入字符串或数字，即使请求需要的数据只有一个，比如token，那返回的data应该为：
// 正确
data: { token: 123456 }
// 错误
data: 123456
接口版本的设计
接口不可能一成不变，在不停迭代中，总会发生变化。接口的变化一般会有几种：
- 数据的变化，比如增加了旧版本不支持的数据类型
- 参数的变化，比如新增了参数
- 接口的废弃，不再使用该接口了
为了适应这些变化，必须得做接口版本的设计。
整个接口系统有统一的版本，一般在URL中添加版本号，比如http://api.xx.com/v2。
比如App1.0使用的接口跟2.0使用的可能不一样，可能会有接口字段调整，类型调整等，这时你又不能丢弃老的用户，还要兼容新的版本，那么这样的版本总体来说可以分大版本和小版本。
大版本
以版本号为路径，比如/api/v1/*，在App做一次大的升级，会出现多个接口大的迁移，这时要考虑到数据的兼容，在适当的时候整体新版本里应用v2资源，升级大版本后相关调整的接口一定要跟客户端开发者约定好，避免兼容问题
小版本
实际工作中难免会经常fix一些问题，或者小的需求改动，比如在登录里加个验证码，这小的改动遵循只添加不删除的规则；
因客户端在请求接口时都会带有App当前的版本号，后端可根据该版本来做一些兼容，比如1.0.1的时候登录不用验证码，1.0.2的时候必须有验证码这样的需求；
当然还有一些设备的兼容，比如ios和android等，当一个接口里小的版本过多时就得考虑升级了。
