8.3 分页查询规范

概述

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

分页入参（common.PageReq）

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

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

分页出参（PageData[T]）

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

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

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

前端 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"``	同上

筛选链执行顺序（固定）

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

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

导出=所见

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

排序规范

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

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

前端分页组件约定

分页组件（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 成本（管理后台低频场景可接受）