logo头像

待到风起时,扬帆济沧海

前后端开发规范

前后端API对接规范

版本 编写人 编写时间 更新内容
1.0.0 徐晨 2019年7月8日 初稿

由前端(APP端)和后端一起协定接口规范的内容, 确定每一个接口的地址(URL), 输入(request)和输出(response), 必要的时候详细注释每一个字段的含义和数据类型.

具体需要定义哪些接口, 可以按照下面的思路来整理

  • 资源接口:系统涉及到哪些资源, 按照 RESTful 方式定义的细粒度接口
  • 操作接口:页面涉及的操作,比如抽奖,领取奖品等,也可以RESTFul 方式定义
  • 页面接口:页面涉及到接口太多,如果是一个个调用会增加频繁请求,对影响用户感知(首屏加载)和性能的尽量做成聚合接口,对并发量较大的接口,建议采用随机延迟加载方式。

接口协商要点

  • 返回统一的数据结构
  • 查询不到时,即空数据情况下的返回的数据格式
  • 接口调用业务失败的常用错误码
  • 接口是否有需要授权
  • 接口是否有Nginx缓存或者CDN缓存
  • 返回数据中包含图片,是否包含完整的URL图片地址
    • 部分:/path/default.jpg
    • 完整:http://res.kelala.com/path/default.jpg
  • 返回数据中的日期格式,是使用时间戳还是格式化好的文字
    • 一些语言unix时间戳是千分位,需要注意
    • 返回给前端的格式化时间应该统一标准,如:2019年7月8日 13:31:24 或者 2019-07-08 13:31:24
  • 长整型,如Java的long,mongodb的自增id等,返回给前端产生的数字溢出,建议采用字符串类型
  • 分页信息定义
    • 分页参数page
    • 分页大小page_size
    • 总记录数 total
    • 当前页 current_page

后端接口通用规范

接口文档标准

接口数据文档必须包含以下内容

  • 接口URL地址
  • HTTP Method(GET\POST\PUT等)
  • 请求参数名称、类型、描述、必选、可选标识
  • 接口返回数据格式、数据字段的意义、类型
  • 接口正常响应格式
  • 接口异常响应内容格式(如果有)

特别注意事项:

  1. 服务端接口出现任何变更开发负责人必须通知对应的接口使用人,接口变更未及时通知使用方;

  2. 接口文档中,除声明HTTP METHOD方法外,还需要区分标明QueryString参数和POST参数,防止调用方出现浏览器缓存、服务端缓存问题。

  3. 如果接口有缓存设计(CDN缓存、Nginx缓存等),需要在接口文档中标明有缓存,调用方不可使用诸如加随机数参数等参数方式形成缓存穿透,避免此方式造成服务端性能问题和出现故障的。

数据基础格式标准

数据输出格式如下,所有接口必须按照次格式

1
2
3
4
5
{
error:0,//错误码 ,error=0 表示无错误,error>0表示有错误
message:"",// 错误详细可读信息
data:{}// 数据字段,内容由接口提供人定义
}

关于错误码取值范围定义

错误码固定方法:

  • 如小于1000以下为保留位数,400错误,500错误,419错误等;
  • 大于1000的表示公共API调用失败,比如授权1401,第三方系统调用失败1690等;
  • 大于10000的表示业务或者项目区分,比如模块A 10000~19999 区分错误码,模块B 20000~29999区分

关于状态位的定义
不允许要求数据使用方在代码里面写死映射关系,应该采取后端返回,例如:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"data": {
"status": 0,
"status_text": "未审核" 
}
}

{
"data": {
"status": 1,
"status_text": "审核中" 
}
}

{
"data": {
"status": 2,
"status_text": "审核通过" 
}
}

数据字段内容规范 :安全警告

  • 包含html代码的数据,为了防止跨站攻击,服务端默认对数据内容全部进行HTML编码,编码标准请参考:转码说明,数据使用方需要对相关数据进行对应编码字符进行显示处理
  • 过滤涉及业务安全和数据敏感的字段,例如参与人数,中奖概率,中奖限制等字段

样板示例

请求字段 类型 是否必须 描述
cate_id int 分类id
  • 响应:

成功

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
"error": 0,
"message": "校验通过",
"data": {
"cate": {
"1": {
"cate_id": "1", // 分类id
"cate_name": "二次元爱好者", // 分类名称
"short_name": "erciy", // 分类url名称
"orderdisplay": "2", // 分类排序
"update_time": "1484550058", // 创建时间
},
......   

}
}

失败:

1
2
3
4
5
{
"error": 10001,
"message": "参数错误",
"data": {}
}


请求字段 类型 是否必须 描述
x-csrf-token string 鉴权参数
  • 请求参数:
请求字段 类型 是否必须 描述
username string 用户名
password string 用户密码
  • 响应:

成功

1
2
3
4
5
{
"error": 0,
"message": "提交成功",
"data": {}
}

评论系统未开启,无法评论!