接口设计规范_接口变更规范

######说明：适用于Web前后端分离

基本规范

参考链接：RESTful API 最佳实践

• 原则上使用RESTful风格，如有特殊可不遵循此规范！！！
• 统一使用RESTful风格的接口请求方式，前端需要模拟除GET，POST以外的请求:
  • GET：读取请求，如列表，详情接口
  • POST：创建请求，如新增一条数据
  • PUT：更新（Update），通常更新整个实体
  • PATCH：部分更新
  • DELETE：删除
• URI统一使用资源实体的方式定义，资源实体统一定为英文单词的复数形式，筛选参数使用查询字段，以用户(User)实体为例
  • GET /users：读取用户列表
  • GET /users?page=1&size=10：分页读取用户列表（第1页，每页10条数据）
  • GET /users/1：读取id为1的用户详情
  • GET /users?source=wechat：读取来自微信的用户
  • POST /users: 创建用户
  • PATCH /users/1:更新id为1的用户信息
  • DELETE /users/1：删除id为1的用户信息
  • GET /users/1/followers：读取id为1的用户的粉丝列表

• 2XX均表示请求成功：
  • GET：200，成功
  • POST：201，创建成功
  • PUT：200，成功
  • PATCH：200，成功
  • DELETE：200，已删除
  • 异步处理：202，服务器已接收到请求，处于待处理状态（如异步操作）。
• 3XX表示重定向：在前后端分离时由前端控制是否跳转
  • 301：永久重定向，浏览器直接跳转
  • 302、307：暂时重定向，浏览器直接跳转
  • 303：暂时重定向，指定跳转URL，前端询问用户是否跳转，如

      HTTP/1.1 303 See Other
      Location: /users/1
    1
    2

• 4XX状态码，表示前端错误
  • 400 Bad Request:无效请求，服务器不理解前端请求
  • 401 Unauthorized：用户没有提供身份凭证凭据或没有通过身份验证（如未登录，登录信息失效）
  • 403 Forbidden：用户通过了验证，但是不具有访问资源所需的权限（功能权限或数据权限）
  • 404 Not Found：请求资源不存在或不可用（如已删除资源）
  • 405 Method Not Allowed：用户已通过验证，但是所用的HTTP方法不符合要求（如GET方法使用POST请求）
  • 410 Gone：资源已从该地址转移，不再可用（如文件转移）
  • 415 Unsupported Media Type：客户端要求的返回格式不支持，如只能返回JSON格式，客户端要求返回XML格式。
  • 422 Unprocessed Entity：客户端上传的实体无法处理（如数据不完整，数据校验不通过），导致请求失败。
  • 429 Too Many Requests：客户端请求的次数超过限额。
• 5XX状态码，服务端错误。要求服务端出错时要捕获异常，提供友好的信息给前端，不暴露异常信息到前端。
  • 500 Internal Server Error：客户端请求有效，服务器处理出现异常（如SQL执行错误，程序执行异常）
  • 503 Service Unavailable：服务器无法处理请求，通常用于网站维护状态

返回格式约定

• 统一采用JWT做鉴权，JWT的访问令牌token通过HTTP Header返回

对于返回HttpStatus为2XX ，表示示例数据如下：

参考分页列表参数

{
    "pageSize": 2,
    "pageNum": 1,
    "total": 6,
    "list": [
        {
            "id": 7,
            "deptName": "xxx部门",
            "deptCode": "001",
            "sort": 1,
            "createOn": null,
            "createBy": "ut ullamco nulla",
            "modifyOn": null,
            "modifyBy": "culpa",
            "delFlag": 1,
            "parentId": 1,
            "enterpriseCode": "1",
            "qywxDeptId": "002",
            "qywxStatus": 1,
            "jdId": null,
            "jdParentId": null,
            "deptPhone": null,
            "deptFax": null,
            "deptAddress": null
        },
        {
            "id": 6,
            "deptName": "我房旅居",
            "deptCode": "001",
            "sort": 1,
            "createOn": null,
            "createBy": "ut ullamco nulla",
            "modifyOn": null,
            "modifyBy": "culpa",
            "delFlag": 1,
            "parentId": 1,
            "enterpriseCode": "1",
            "qywxDeptId": "002",
            "qywxStatus": 1,
            "jdId": null,
            "jdParentId": null,
            "deptPhone": null,
            "deptFax": null,
            "deptAddress": 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

参考无分页列表参数

[
    {
        "id": 7,
        "deptName": "xxx部门",
        "deptCode": "001",
        "sort": 1,
        "createOn": null,
        "createBy": "ut ullamco nulla",
        "modifyOn": null,
        "modifyBy": "culpa",
        "delFlag": 1,
        "parentId": 1,
        "enterpriseCode": "1",
        "qywxDeptId": "002",
        "qywxStatus": 1,
        "jdId": null,
        "jdParentId": null,
        "deptPhone": null,
        "deptFax": null,
        "deptAddress": null
    },
    {
        "id": 6,
        "deptName": "我房旅居",
        "deptCode": "001",
        "sort": 1,
        "createOn": null,
        "createBy": "ut ullamco nulla",
        "modifyOn": null,
        "modifyBy": "culpa",
        "delFlag": 1,
        "parentId": 1,
        "enterpriseCode": "1",
        "qywxDeptId": "002",
        "qywxStatus": 1,
        "jdId": null,
        "jdParentId": null,
        "deptPhone": null,
        "deptFax": null,
        "deptAddress": 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

参考单个对象参数

{
    "id": 1,
    "deptName": "xxx集团",
    "deptCode": "dfsadf",
    "sort": null,
    "createOn": "2019-04-16T01:02:29.000+0000",
    "createBy": null,
    "modifyOn": "2019-04-16T01:02:29.000+0000",
    "modifyBy": null,
    "delFlag": 0,
    "parentId": null,
    "enterpriseCode": "1",
    "qywxDeptId": null,
    "qywxStatus": null,
    "jdId": null,
    "jdParentId": null,
    "deptPhone": null,
    "deptFax": null,
    "deptAddress": null
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

对于返回HttpStatus为3XX、4XX、5XX ，表示示例数据如下：

//对于错误提示信息，规则如下：前端先获取二级错误信息data信息展示，如二级错误信息为null，则展示一级错误msg信息
 {
    data:  "密码不少于6位",
    code: 2004, 
    msg: "Password does not comply with regulations  "
    sys:"naliwan"
}
//多条错误明细
 {
    data:  [{"message":"密码不少于6位"},{"message":"密码必须包含数字和字母"}],
    code: 2004, 
    msg: "Password does not comply with regulations  "
    sys:"naliwan"
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

业务错误码说明

2004

1.系统级错误码