1.3 KiB
1.3 KiB
12.2 分页查询规范
:::tip 必须遵守 列表查询一律用分页契约：请求内嵌 PageReq，响应为 PageData 五字段。禁止自造分页参数名或响应结构。 :::
契约
请求：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 不设上限 | 一次拉爆内存 |