从零搭建WebApi接口开发框架-接口规范

因为是接口框架，首先要做的就是制定接口规范，好的接口规范能约束开发人员，能降低前后端人员之间的沟通协调，能避免后期联调带来的一系列问题。

1.接口规范
接口规范包含以下内容：
1、请求类型及参数
2、返回值及返回码
3、权限及版本控制
4、接口示例
2.接口请求说明
Api使用Restful风格，接口地址（测试）：http://host:port
（接口描述中地址需要扩展自此地址，如/api/users/register，扩展后则为 http://host:port/api/users/register）
接口请求类型分为两种，GET和POST，GET通常为请求获取资源；POST通常为提交资源到服务器；
接口请求返回值基本分为两种：
GET的请求若无错误，则返回所需资源的JSON格式内容，若有错误则返回一致的JSON格式内容，如：{“success”:false, “message”: “提交的参数不正确”, data: {}}，其中data为额外的对象，具体值根据接口而定；
POST的请求的Body部分可以将对象格式化为JSON的字符串后提交，也可以使用传统的Form表单形式提交， 返回一致的JSON格式内容：如：{“success”:true, “message”: null, data: {id:1}}，其中data的内容也是具体根据接口而定。
返回码说明：

200 请求成功
400 客户端请求时所提交的参数不正确（通常为客户端的问题）
401 未提供accessToken（即未登录）
403 权限不足（已登录，但不具有访问该资源的权限）
404 找不到该资源（通常为请求的地址不正确）
500 服务发生错误（通常为服务端的问题）

实际生产中，请求基本都为POST
3.接口权限说明
接口权限验证使用OAUTH2.0标准，即先请求授权服务获取accessToken，得到accessToken后使用其内容封装到request的头（Headers）中，用以请求被保护的资源；
accessToken封装在Headers中是以Authorization键值对形式组成的，如：accessToken为4cac113f-29b1-4585-99a8-16e39331ccb3，封装的内容为：Authorization: 4cac113f-29b1-4585-99a8-16e39331ccb3这种形式。
4.接口请求版本说明
各个接口在header里面都加Version字段，用于控制接口的版本，服务端程序可以根据版本号来动态返回数据，也可以根据版本号来提示app升级。不加version默认1.0。
5.公共返回码
为了保证接口的规范性，特制定标准返回码：
成功类：

10001 保存成功
10002 删除成功
10003 操作成功
10004 审核成功

失败类

20001 操作失败
20002 代码已存在
30001 无权限
30002 系统错误
30003 参数错误
30004 路径不存在

5.接口示例

接口示例.png

上述是登录接口的文档标识

总结
设计接口规范是一个相当复杂的事情，要综合考虑很多技术及实现细节。后续章节依次讲述这些细节，并不断完善规范文档。