# 8.3 分页查询规范

:::tip 概述
分页契约三件套：PageReq 入参（pageNo/pageSize）+ PageData 出参（records/total/size/current/pages）+ 筛选对齐三件套（querySchemas ↔ Req 字段 ↔ spec 声明）。导出与列表同套筛选。
:::

## 分页入参（common.PageReq）

```text
pageNo    页码，默认 1
pageSize  每页条数，默认 10，上限 500（GetPageSize 截断——防恶意大 pageSize）

请求示例：GET /api/user/page?pageNo=1&pageSize=10&keyword=张
```

## 分页出参（PageData[T]）

```json
{
  "records": [], "total": 0, "size": 10, "current": 1, "pages": 0
}
```

records 为空输出 `[]` 而非 null（前端无需判空兼容）。

## 筛选对齐三件套（2026-10-14 定稿）

```text
前端 querySchemas.ts 每个筛选输入
  ↔ XxxPageReq 同名驼峰字段
    ↔ logic spec 声明

字符串 Input        → LikeFields（逐列模糊，值取 req 同名字段，空跳过）
Select/InputNumber  → EqFields（等值，零值跳过）
关键词框（可选）     → KeywordFields（req.keyword 多列 OR）
                      ——能力保留在基座，模块默认不声明，需要时再用
```

### 对齐示例（example 模块）

| 前端 querySchemas | 后端 PageReq | spec 声明 |
|-------------------|-------------|-----------|
| `field: 'name'`（Input） | `Name string \`json:"name"\`` | LikeFields: []string{"name"} |
| `field: 'type'`（Select） | `Type int \`json:"type"\`` | EqFields: []string{"type", "status"} |
| `field: 'status'`（Select） | `Status int \`json:"status"\`` | 同上 |

### 筛选链执行顺序（固定）

```text
applyFilters：LikeFields → EqFields → KeywordFields → Filter → DataScope
前置：dao.Ctx 已注入 del_flag=0 + 租户 IN(0,自身)
```

复杂条件写 Filter 钩子，**不要重复 Like/Eq 已覆盖的条件**。

## 导出=所见

```text
导出接口统一走 xxxSpec.applyFilters 与列表同套筛选：
  Export 请求结构含与 PageReq 相同的筛选字段（不带 pageNo/pageSize）
  → applyFilters 同链过滤 → 全量（ChunkQuery 分批）→ Excel
保证：列表看到什么，导出就是什么（含数据权限过滤）
```

## 排序规范

```text
spec.OrderBy          默认排序（如 "id DESC"、"sort, id"）
spec.ListOrderBy      列表专用排序
spec.OrderableFields  前端排序白名单（orderField/orderType 仅白名单内生效）
```

前端排序参数不可直通 SQL——白名单外的排序字段忽略（防注入）。

## 前端分页组件约定

```text
分页组件（components/pagination）：
  change 事件携带 pageNo/pageSize → 重新请求 /page
  pageSize 切换回到第 1 页
  上限保护：≤500（与后端 GetPageSize 截断一致）
```

## 开发规约

+ 分页接口 PageReq 内嵌 common.PageReq（复用默认值与截断逻辑）
+ 筛选字段必须三件套对齐——querySchemas 加了输入，Req 与 spec 都要跟上
+ 字符串筛选走 LikeFields 声明（列名显式声明，值取 req 同名驼峰字段）
+ 零值跳过是 EqFields 语义（status=0 是有效筛选值时需在 Filter 处理或调整字段设计）
+ 大表分页深翻页注意：pageNo×pageSize 过大时的 offset 成本（管理后台低频场景可接受）