71 lines
2.0 KiB
Markdown
71 lines
2.0 KiB
Markdown
# 8.3 分页查询规范
|
||
|
||
:::tip 概述
|
||
分页契约三件套：请求内嵌 `PageReq`、响应为 `PageData[T]`、默认与上限有兜底。前后端与生成器共享同一结构，无每个模块重定义。
|
||
:::
|
||
|
||
## 请求（PageReq）
|
||
|
||
```go
|
||
// 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]）
|
||
|
||
```go
|
||
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"` // 总页数
|
||
}
|
||
```
|
||
|
||
## 请求响应示例
|
||
|
||
```json
|
||
// GET /api/example/page?pageNo=1&pageSize=10&name=测试
|
||
{
|
||
"code": 0, "ok": true, "msg": "操作成功",
|
||
"data": {
|
||
"records": [],
|
||
"total": 0, "size": 10, "current": 1, "pages": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
## 服务端流水线
|
||
|
||
```text
|
||
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。
|
||
|
||
## 下一步
|
||
|
||
→ [8.4 请求绑定与参数校验](/zh/api-spec/binding.html)
|