API接口设计方案

接口路径的设计

路径是指后端提供给前端调用该接口的地址，其实就是该接口的链接，最好以一个较为明显的词为开头，或者说以单独的域开头，路径还要向语义化靠拢，这里只是路径，不涉及到参数，比如：

http://api.xx.com/bid/list.htm
http://api.xx.com/bid/list.htm

注：通常是复数时会在词后加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的时候必须有验证码这样的需求；