API 分页方案设计(免费版)
输入
| 字段 | 必填 | 说明 |
|---|---|---|
| page / page_size | 是 | 页码(从1起)/每页条数 |
| total | 是 | 总记录数 |
| items / limit / cursor | 游标分页必填 | 全量列表/每页数/起始游标 |
输出
offset 偏移量 + 总页数 + 是否有下一页 + 游标切片(本页数据,下一游标)
工作流
- offset 分页:offset=(page-1)×page_size,适合浅分页。
- 总页数=ceil(total/page_size);page<总页数 才有下一页。
- 游标分页适合深分页/实时数据:从 cursor 切 limit 条,next_cursor=cursor+本页条数。
硬性规则
- page≥1、page_size≥1,非法值报错不静默。
- total=0 时总页数为0,不做除零。
- 游标不为负,下一游标不超过列表长度。
示例
offset(3,20)=40;total_pages(95,20)=5
游标[0..9] limit3 cursor0 → 前3条,next=3,有下一页