唯品秀前端博客
当前位置: 别具匠心 > 【YQN】前后端对接接口API规范

【YQN】前后端对接接口API规范

2018-04-23 分类:别具匠心 作者:管理员 阅读(2645)

1 接口数据通用原则

避免多数据源
  1. 避免通过多接口调用获取数据来完成一个渲染逻辑的需求。
  2. 尽可能避免通过A接口调用获取数据,请求B接口获取数据的级联请求来完成一个渲染逻辑的需求。
扁平数据结构
  1. 接口返回值应该尽可能保持结构扁平,谢绝嵌套层级过深的接口数据。
  2. 数据层级尽量压缩在3层以内。
不关注业务逻辑
  1. 前端关注交互、渲染逻辑,尽量避免业务逻辑处理的出现。
  2. JavaScript在浮点数据计算精度上有比较明显的精度误差,而且前端数据皆不可信,所以不要把业务计算逻辑放到前端(尤其是浮点数计算)。推荐计算后再接口里直接返回。
默认值统一
  1. 页面字段默认值需要约定契约的时候就明确好。
  2. 无值的默认值不可以是0。通用无值的默认值为null或者空的字符串。
  3. 接口返回字段的格式推荐为string格式。

2 请求基本格式

GET 请求
1
2
// http://xxx/api/xxx/xxx
// http://xxx/api/xxx/xxx?key1=value1&key2=value2&key3=value3
POST 请求
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
// http://xxx/api/xxx/xxx
// 通用请求体
{
    key1: 200,
    key2: '响应消息',
    key3: {
        xxx: '',
        yyy: {},
        zzz: []
    },
    key4: [
        {
            xxx: 1,
            yyy: '',
            zzz: {}
        },
        {
            xxx: 2,
            yyy: '',
            zzz: {}
        }
    ]
}

// 通用列表请求体
{
    // 列表业务用参数
    key1: 200,
    key2: '响应消息',
    // 列表格式用参数
    page: 1,                      // 请求页码(require)
    size: 20,                     // 请求每页展示数(require)
    sort: [
        {                         // 列表排序方式
            property: 'id',       // 排序属性的key
            direction: 'ASC'      // 排序方式    ASC[升序] | DESC[降序]
        }
    ]
}

3 响应基本格式

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
85
86
87
88
89
90
// 通用对象返回
{
    code: 200,                       // 响应状态码(require)
    msg: '响应消息',                  // 响应消息体(require)
    data: {                          // 响应数据体(require)
        xxx: '',
        yyy: {},
        zzz: []
    }
}

// 通用数组返回
{
    code: 200,                       // 响应状态码(require)
    msg: '响应消息',                  // 响应消息体(require)
    data: [                          // 响应数据体(require)
        {
            xxx: '',
            yyy: {},
            zzz: []
        }
    ]
}

// 通用列表返回(带分页查询)
{
    code: 200,                        // 响应状态码(require)
    msg: '响应消息',                   // 响应消息体(require)
    data: {
        content: [                    // 列表数据体(require)
            {
                xxx: '',
                yyy: {},
                zzz: []
            }
        ],
        sort: [
            {                         // 列表排序方式
                property: 'id',       // 排序属性的key
                direction: 'ASC'      // 排序方式    ASC[升序] | DESC[降序]
            }
        ],
        page: 1,                      // 当前页码(require)
        size: 20,                     // 每页展示数(require)
        total: 200,                   // 列表总数(require)
        totalPage: 10,                // 列表总页数(require)
        isLast: 0                     // loadmore用,是否最后一页(require)
    }
}

// 无数据返回格式需要按照数据体类型返回对应空数据体
{
    code: 200,                       // 响应状态码(require)
    msg: '响应消息',                  // 响应消息体(require)
    data: {}                         // 无数据(require)
}

{
    code: 200,                       // 响应状态码(require)
    msg: '响应消息',                  // 响应消息体(require)
    data: []                         // 无数据(require)
}

{
    code: 200,                        // 响应状态码(require)
    msg: '响应消息',                   // 响应消息体(require)
    data: {
        content: [],                  // 无数据(require)
        sort: [{}],
        page: 1,                      // 当前页码(require)
        size: 0,                      // 每页展示数(require)
        total: 0,                     // 列表总数(require)
        totalPage: 0                  // 列表总页数(require)
        isLast: 1                     // loadmore用,是否最后一页(require)
    }
}

// 请求失败(网络不通,环境不对导致)
{
    code: 500,                        // 错误状态码(require)
    msg: '响应消息',                   // 错误消息体(require)
    data: {}                          // (require)
}

// 请求失败(业务错误)
{
    code: XXXXX,                      // 建议4-5位数错误码,用来和系统级别,通用错误码区分开来(require)
    msg: '响应消息',                   // 错误消息体(require)
    data: {}                          // (require)
}
code请求处理状态码通用约定
  1. 200: 请求处理成功
  2. 500: 请求处理失败
  3. 401: 用户未登录,跳转登录页
  4. 403: 用户无权限,展示无权限

4 特殊内容规范

Boolean类型
  1. 关于Boolean类型,JSON数据传输中推荐使用1/0来标示,1为是/True,0为否/False。
日期类型
  1. 关于日期类型,JSON数据传输中一律使用字符串,日期格式使用时间戳。
循环体唯一key
  1. MVVM框架(React,Vue)的高速更新机制使得循环体(LIST)需要一个LIST数据的稳定唯一key。
  2. 前端自己使用index或者自己生成不够稳定,因此需要接口对于LIST类型的数据返回一个稳定的唯一key。

「两年博客,如果觉得我的文章对您有用,请帮助本站成长」

赞(7) 打赏

谢谢你请我吃鸡腿*^_^*

支付宝
微信
7

谢谢你请我吃鸡腿*^_^*

支付宝
微信

上一篇:

下一篇:

共有 0 条评论 - 【YQN】前后端对接接口API规范

博客简介

唯品秀博客: weipxiu.com,一个关注Web前端开发技术、关注用户体验、坚持更多原创实战教程的个人网站,愿景:成为宇宙中最具有代表性的前端博客,期待您的参与 

精彩评论

友情链接

他们同样是一群网虫,却不是每天泡在网上游走在淘宝和网游之间、刷着本来就快要透支的信用卡。他们或许没有踏出国门一步,但同学却不局限在一国一校,而是遍及全球!申请交换友链

站点统计

  • 文章总数: 220 篇
  • 草稿数目: 0 篇
  • 分类数目: 14 个
  • 独立页面: 6 个
  • 评论总数: 969 条
  • 链接总数: 13 个
  • 标签总数: 406 个
  • 建站时间: 950 天
  • 注册用户: 1417 人
  • 访问总量: 8708315 次
  • 最近更新: 2019年7月17日
服务热线:
 173xxxx7240

 QQ在线交流

 旺旺在线