关于团队API接口规范设计
这篇文章主要介绍我在一家移动互联网企业的做的接口规范文档，这篇文档帮助团队内部的协作起到很大的作用。可能文章内容会掺杂个人对接口的理解，各位大佬望批评指正。
更新记录
- 2019-09-21 marker 新增Java代码规范
- 2019-08-30 marker 发布规范
一、接口签名规则
签名参数为sign，参数排序，md5加密得到sign，所有的app接口都需要验签。
| sign = md5(参数排序 + time) |
注意：接口的签名规则是保密的，不应该公布，这里提供简单的伪代码案例。
二、接口参数规范
接口参数统一使用表单模式提交，主要有requestbody和form表单，为了规范参数提交，我们统一采用的表单方式。虽然说Java SpringMVC有强大的参数解析器，能自动封装为实体Bean，提供统一的参数规范能降低技术维护成本。
注意：除非特殊的业务需要使用body提交数据的，所有开发人员统一使用表单方式提交。
三、接口请求头规范
- DEVICEINFO头 值为json格式，主要为了接口判断实现接口兼容等操作。
| json字段 | 说明 |
| vc | 版本code |
| ver | 版本名 |
| ot | 终端类型 (ios、android、web) |
- Authorization 头认证鉴权，Spring Security 验证Token的头参数。
四、接口地址规范
用户端前缀：api/app ，商户端前缀：api/biz
| 规范 | 说明 |
| 接口地址 | /api/app/业务名/ |
| 接口地址（含子业务） | /api/app/业务名/子业务 |
| 业务字段接口地址 | /api/app/业务名/字段 |
| 请求方法 | GET(查)、PUT(修改)、DELETE（删除）、POST（添加） |
| 码表业务接口 | /api/app/code/数据对象 |
| 列表查询接口地址 | /api/app/业务名/list ， /app/业务名/子业务/list |
| 无需登录可调用接口 | /api/app/open/* |
五、接口返回数据规范
除登录Oauth相关接口以外，响应数据结构都为。
| {
“code”: “S00”, “msg”: “操作成功”, “timestamp”: “2019-08-28T09:53:21.434Z”, “data”: { } } |
六、接口数据校验失败
后端做的数据校验由多字段校验失败的情况。
| {
“code”: “000026”, “data”: [ { “field”: “productNum”, “msg”: “产品编号不能为空” }, { “field”: “productName”, “msg”: “产品名称不能为空” } ], “msg”: “提交数据校验错误”, “timestamp”: “2019-10-06 06:02:27” } |
七、Java内部接口规范
- controller层、business层、service层、 mapper层APP 端接口需带有app标识，便于识别app端代码；
- 不能将APP的与运营后端的业务代码共用，提别是分页或列表查询的sql不能共用，避免解决一端问题另一端又产生bug；
- 所有的金额计算必须使用BigDecimal科学计算方式；
- 复杂数据结构的使用JSONObject 或Map 构造数据返回给前端；
- app端接口大部分使用字符返回，除需要业务判断的使用基本类型；
关注微信公众帐号