2.0 KiB
2.0 KiB
8.3 分页查询规范
:::tip 概述
分页契约三件套：请求内嵌 PageReq、响应为 PageData[T]、默认与上限有兜底。前后端与生成器共享同一结构，无每个模块重定义。
:::
请求（PageReq）
// internal/model/dto/common.go
type PageReq struct {
PageNo int `json:"pageNo" form:"pageNo" dc:"页码，从1开始，默认1"`
PageSize int `json:"pageSize" form:"pageSize" dc:"每页条数，默认10，最大500"`
}
| 参数 | 默认 | 边界 |
|---|---|---|
| pageNo | 1 | <=0 时取 1（GetPageNo 兜底） |
| pageSize | 10 | 上限 500（GetPageSize 兜底，防超大页拖库） |
GET 请求经 form 标签绑定 query 参数。
响应（PageData[T]）
type PageData[T any] struct {
Records []T `json:"records"` // 当前页记录
Total int `json:"total"` // 总记录数
Size int `json:"size"` // 每页条数（回显实际生效值）
Current int `json:"current"` // 页码（回显实际生效值）
Pages int `json:"pages"` // 总页数
}
请求响应示例
// GET /api/example/page?pageNo=1&pageSize=10&name=测试
{
"code": 0, "ok": true, "msg": "操作成功",
"data": {
"records": [],
"total": 0, "size": 10, "current": 1, "pages": 0
}
}
服务端流水线
PageReq 兜底（GetPageNo/GetPageSize）
→ ModuleSpec.applyFilters（LikeFields/EqFields/Keyword/Filter/DataScope）
→ Count 总数 + Offset/Limit 查询
→ NewPageData 组壳（records 空输出 []）
前端约定
- 分页组件绑定 pageNo/pageSize，变更即重查
- 列表为空渲染
[]（不判 null） - 筛选条件与分页参数同请求发送（重置筛选时回到第 1 页）
List（不分页）的对应物
全量列表用 List 接口：limit 参数可选限制条数（0=不限），响应为平铺数组。下拉数据源等小数据量场景用 List，列表页用 Page。