前后端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
          }
        ]
      }
    }
}