关于团队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端接口大部分使用字符返回,除需要业务判断的使用基本类型;

 

 

来源: 雨林博客(www.yl-blog.com)