69 lines
2.5 KiB
Markdown
69 lines
2.5 KiB
Markdown
# 12.2 分页查询规范
|
||
|
||
:::tip 概述
|
||
必须遵守的查询契约：筛选对齐三件套、分页默认值与上限、导出=所见、排序白名单。机制详解见 [8.3 分页查询规范](../api-spec/pagination)。
|
||
:::
|
||
|
||
## 强制规范（三件套对齐）
|
||
|
||
```text
|
||
1. 前端 querySchemas.ts 每个筛选输入 ↔ XxxPageReq 同名驼峰字段 ↔ spec 声明
|
||
——三处任一缺失即视为筛选缺陷
|
||
|
||
2. 组件类型与后端声明对应：
|
||
字符串 Input → LikeFields（逐列模糊，列名显式声明）
|
||
Select/InputNumber → EqFields（零值跳过）
|
||
KeywordFields（req.keyword 多列 OR）能力保留在基座，模块不声明，需要时再用
|
||
|
||
3. 分页：PageReq 内嵌 common.PageReq（pageNo 默认 1；pageSize 默认 10 上限 500）
|
||
|
||
4. 导出统一走 xxxSpec.applyFilters 与列表同套筛选（导出=所见，含数据权限）
|
||
|
||
5. 排序：前端排序字段仅 OrderableFields 白名单内生效（防注入）
|
||
|
||
6. 复杂条件写 Filter 钩子——不重复声明 Like/Eq 已覆盖条件
|
||
```
|
||
|
||
## spec 声明模板（标准形态）
|
||
|
||
```go
|
||
var xxxSpec = ModuleSpec[...]{
|
||
Model: dao.Xxx.Ctx,
|
||
LikeFields: []string{"name"}, // 对应 querySchemas 的 Input
|
||
EqFields: []string{"status", "type"}, // 对应 Select/InputNumber
|
||
OrderBy: "id DESC",
|
||
// DataScope: ApplyDataScope("dept_id"), // 有部门列且需行级权限时
|
||
}
|
||
```
|
||
|
||
## Review 检查项
|
||
|
||
```text
|
||
□ querySchemas 新增输入 → Req 加字段 + spec 加 Like/Eq 声明（三件同步）
|
||
□ Req 筛选字段命名与表单 field 完全一致（驼峰）
|
||
□ 导出接口 ExportReq 携带同套筛选字段且走 applyFilters
|
||
□ 排序字段在白名单内
|
||
□ 零值语义确认（status=0 为有效筛选时的处理）
|
||
□ 分页上限未绕过（未自定义 pageSize 无上限）
|
||
```
|
||
|
||
## 反例（禁止）
|
||
|
||
```text
|
||
❌ querySchemas 有输入但 Req 无字段（提交了后端不读）
|
||
❌ Req 有字段但 spec 未声明（读了不过滤——筛选假生效）
|
||
❌ 导出另写查询条件（导出 ≠ 所见）
|
||
❌ Filter 里重复写 LikeFields 已覆盖的条件
|
||
❌ 前端传 orderField 直通 SQL（必须白名单）
|
||
❌ 手写 del_flag/tenant_id 条件混入筛选（dao.Ctx 已注入）
|
||
```
|
||
|
||
## 一致性验证方法
|
||
|
||
```text
|
||
1. 页面输入筛选值 → Network 看请求参数
|
||
2. 对照 Req 字段名（驼峰）是否接收
|
||
3. 对照 spec 声明过滤是否生效（结果集变化）
|
||
4. 导出同一筛选 → Excel 行数 = 列表 total
|
||
```
|