# 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)