91 lines
3.2 KiB
Markdown
91 lines
3.2 KiB
Markdown
# 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 成本（管理后台低频场景可接受）
|