分页
分页规范
2018-05-16 温家锦
基本字段定义
method
get
request
page_obj O string 起始页（不包含），默认第0页
reverse O bool 是否反向查询。1：是，0：不是。默认为否。
limit O int 返回条数，默认10。传0表示返回所有数据。
offset O int 查询起点偏移条数，默认 0 [注1]
peek O int 是否需要 peek，默认不需要 peek。peek 必须大于 limit。
count O bool 是否需要 count，默认不需要 count。（部分接口可能不实现本功能, 因为如果数据量极大，count 会很耗时）
response
{
"code": 0
"msg": "ok"
"data": {
"users": [
{"id": 1, "name": "A"},
{"id": 2, "name": "B"},
{"id": 3, "name": "C"}
]
},
"pagination": { M dict
"peek": 100, O int 前端传 peek 的话，后端就会返回这个字段
"more": true, M bool 是否有更多数据
"page_obj": "gtyuhbgyhbvgyhgvgy", M string
"count": 2000 O int 前端传 count 的话，后端就会返回这个字段
}
}
[注1]：reverse, offset, peek, count 的原理可以参考【旧】分页规范详解，不过和本文档相冲突的部分以本文档为准。
～
字段详细定义
offset:
- 这里的 offset 是基于当前用户所在页的 offset，和数据库中 offset 的定义（基于第 0 个元素）不同
- offset 不能为负数
- 如果用户点击上一页（reverse=1），则 offset 是基于当前页的第一个元素，向上一页的方向跳过 offset 个元素
- 如果用户点击下一页（reverse=0），则 offset 是基于当前页的最后一个元素，向下一页的方向跳过 offset 个元素
peek:
peek 包含 limit 的部分（所以响应里的 peek 总是大于等于响应里 data 的长度）、不包含 offset 的部分
data:
无论 reverse 是 true 还是 false，后台中 data 中数组的顺序都是按照展示顺序排好序的。不会出现因为 reverse 为 true 导致后台返回的数据顺序颠倒的情况
count:
符合条件的所有数据量。这个字段对性能影响较大，希望前端能尽量减少请求 count 的次数
图解 peek 和 offset
peek 的定义如下：
ID |
-- |
1 | --------------------------------------+
2 | |
3 | |
4 | |
5 | |
6 | |
7 | --* |
8 | ʌ |
9 | | request: |
10 | | limit: 12 |
11 | | peek: 20 |
12 | | reverse: 1 |
13 | | page_obj: "abc" |
14 | | response.pagination: |
15 | | peek: 18 |
16 | | more: true |
17 | | page_obj: 'abcd' |
18 | --+ ----------------------------------+
19 | --+
20 | |
21 | |
22 | |
23 | | current pages
24 | | 10 **datas**
25 | |
26 | |
27 | |
28 | --+
29 | --+ ----------------------------------+
30 | | |
31 | | request: |
32 | | page_obj: "xyz" |
33 | | limit: 10 |
34 | | peek: 20 |
35 | | reverse: 0 |
36 | | |
37 | V response.pagination: |
38 | --+ peek: 20 |
39 | more: true |
40 | page_obj: "jpeg" |
41 | |
42 | |
43 | |
44 | |
45 | |
46 | |
47 | |
48 | --------------------------------------+
49 |
50 |
offset 的定义如下：
ID |
-- |
1 | --* ----------------------------------+
2 | ʌ request: ʌ
3 | | limit: 10 |
4 | | peek: 20 |
5 | | reverse: 1 |
6 | | offset: 9 |
7 | | page_obj: "abc" |
8 | | response.pagination: |
9 | | peek: 9 |
10 | --+ -- more: false -----------+
11 | page_obj: "efgh"
12 |
13 |
14 |
15 |
16 |
17 |
18 |
19 | --+
20 | |
21 | |
22 | |
23 | | current page
24 | | 10 datas
25 | |
26 | |
27 | |
28 | --+
29 |
30 |
31 | --+ ----------------------------------+
32 | | |
33 | | request: |
34 | | page_obj: "xyz" |
35 | | limit: 10 |
36 | | peek: 20 |
37 | | offset: 2 |
38 | | reverse: 0 |
39 | V response.pagination: |
40 | --+ peek: 20 |
41 | more: true |
42 | page_obj: "y6y6" |
43 | |
44 | |
45 | |
46 | |
47 | |
48 | |
49 | V
50 | --------------------------------------+