42 lines
1.3 KiB
Markdown
42 lines
1.3 KiB
Markdown
# 12.2 分页查询规范
|
||
|
||
:::tip 必须遵守
|
||
列表查询一律用分页契约：请求内嵌 PageReq，响应为 PageData 五字段。禁止自造分页参数名或响应结构。
|
||
:::
|
||
|
||
## 契约
|
||
|
||
```text
|
||
请求：pageNo（默认 1）/ pageSize（默认 10，上限 500）
|
||
响应：records / total / size / current / pages
|
||
```
|
||
|
||
## 服务端规约
|
||
|
||
- 请求结构内嵌 `dto.PageReq`，不手写 pageNo/pageSize 字段
|
||
- 分页经 ModuleSpec.Page 委托（自动兜底与组壳）
|
||
- records 空时输出 `[]`（NewPageData 保证）
|
||
- 深翻页由 pageSize 上限兜底；特殊大导出走 Export 而非超大分页
|
||
|
||
## 前端规约
|
||
|
||
- 分页组件绑定 pageNo/pageSize，变更即重查
|
||
- 筛选变化回到第 1 页
|
||
- 判空按 `records.length`（不判 null）
|
||
|
||
## List（全量）的边界
|
||
|
||
下拉数据源等小数据量用 List + limit 上限；**任何面向页面表格的数据必须走 Page**。导出用 Export（服务端流式写出），不以"大 pageSize 分页"替代。
|
||
|
||
## 反例
|
||
|
||
| 反例 | 问题 |
|
||
|---|---|
|
||
| 自造参数 offset/limit/size 混用 | 与基座、生成器、前端组件不兼容 |
|
||
| 响应只回数组不回 total | 前端无法渲染分页条 |
|
||
| pageSize 不设上限 | 一次拉爆内存 |
|
||
|
||
## 相关
|
||
|
||
- [8.3 分页查询规范](/zh/api-spec/pagination.html)
|