# 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)