前后端API接口文档规范

流程定义

后端编写和维护接口文档,在 API 变化时更新接口文档
前端、后端根据接口文档进行接口开发
开发中自行调试测试,开发完成后联调和提交测试

职责分离

前后端仅仅通过异步接口 (Ajax、Jsonp、Axios 、Request) 来编程
前后端都各自有自己的开发流程,构建工具,测试集合
关注点分离,前后端变得相对独立并松耦合,分而不离、离而不分

URL规范

不能使用大写,用中横线 - 不用下划线 _ 
使用名词表示资源集合,使用复数形式(为确保所有API URIs保持一致)
每个资源都至少有一个标识它的URI,同时应该遵循一个可预测的层次结构来提高可理解性,从而提高可用性

协议规范

  • GET 用于获取资源。不允许对服务器上资源做任何修改操作,常用于数据查询(列表、可用于分页、排序、过滤)
  • POST 用于创建新资源。查询字段(10条以上)内容、更新和删除资源(2条以上),用户登录及敏感数据统一使用POST方式
  • PUT 用于完整的替换资源或者创建指定身份的资源
  • DELETE 用于删除某个资源
  • PATCH 用于局部更新资源

接口参数

1
2
3
4
5
Content-Type: application/json; charset=utf-8 //非必要情况下默认使用 application/json 

Respone
herder 'Access-Token' //自定义token 名称,每次异步请求都需要携带,后端验证鉴权用户信息

状态码 Respone

1
2
3
4
5
6
7
8
9
200  =>  //服务器成功返回请求的数据或者通信成功
400 => //请求有错误,服务器没有进行新建或修改数据的操作
401 => //没有权限(令牌、用户名、密码错误)
403 => //得到授权(与401错误相对),但是访问是被禁止的
404 => //请求记录不存在,服务器没有进行操作
500 => //服务器发生错误,无法判断发出的请求是否成功
502 => //作为网关或者代理工作的服务器尝试执行请求时,从上游服务器接收到无效的响应
503  => //由于临时的服务器维护或者过载,服务器当前无法处理请求
......

返回格式

返回字段须有msg、code必须有值,接口文档对应字段应和后端返回一致,后台返回数据字段需都在data里,不得在data之外。后台返回值为空时,需返回相对应的键名并值为null

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
datatime => [
后端 => int => 默认长度11
前端 => Number => 转换13位 => 依据业务需求转换格式化显示
]

code = {
100200: '服务端数据查询成功',
100400: '服务端业务异常',
100401: '无权限(令牌或者密码错误)',
100404: '当前接口不存在或者已删除',
100500: '服务端发生未知错误'
}

{
    'code'100200, // => 成功为 100200
    'msg''数据通信成功,读取正常 ...',
    'data': {
      'id'1001,
      'name''蓝思同学',
      'username''admin',
      'avatar''https://gw.alipayobjects.com/zos/rmsportal/jZUIxmJycoymBprLOUbT.png',
      'status'1,
      'telephone''',
      'lastLoginIp''27.154.74.117',
      'lastLoginTime'1534837621348,
      'creatorId''admin',
      'createTime'1497160610259,
      'lang''zh-CN',
      'token''4291d7da9005377ec9aec4a71ea837f'
    }
}

{
"msg": "返回成功",
"status": "200",
"data": {
"userInfo":{
"id": null, // 数据类型String,空时为null
"name":"张三",
"age":20 , // 数据类型为Number, 空时为null,
"images": ['地址1''地址2'] //类型Array, 空时为null
"photo": null
},
"list": { //类型:Object 必有字段 备注:分页信息
"total":1, //类型:Number 必有字段 备注:总条数
"pages":1 //类型:Number 必有字段 备注:总页数,
"size": 20 //类型:Number 必有字段 备注:分页数量,
"data": [
{
"id": 21,
"company_id": 4,
"logo": "http://dummyimage.com/70x70/a379f2/FFF&text=L",
"work_name": "经验不限",
"salary_id": 2,
"price": {
'sign': '¥',
'value': 18000.00,
'unit': "月"
},
"education_id": 2,
"addtime": 1595640542,
"work_time": "8小时",
"position_id": 4
},
{
"id": 27,
"company_id": 3,
"logo": "http://dummyimage.com/70x70/79f2c1/FFF&text=L",
"work_name": "经验不限",
"salary_id": 1,
"price": {
'sign': '¥',
'value': 15000.00,
'unit': "月"
},
"education_id": 1,
"addtime": 1595640542,
"work_time": "8小时",
"position_id": 3
}
]
}
}
}