# 12.2 分页查询规范

:::tip 概述
所有分页接口遵循统一的参数命名和返回结构，确保前后端一致性。
:::

## 请求参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `pageNo` | number | 1 | 页码（最小为 1） |
| `pageSize` | number | 20 | 每页条数（1~100） |
| `orderField` | string | - | 排序字段（camelCase，如 `createTime`） |
| `orderType` | string | `desc` | 排序方向（`asc` / `desc`） |
| `fields` | string | - | 返回字段（逗号分隔，如 `id,username,status`） |
| 其他参数 | - | - | 按 Logic 中 pageLikeFields / pageEqFields 自动匹配 |

## 请求示例

```bash
# 基本分页
GET /api/example/page?pageNo=1&pageSize=10

# 带模糊搜索
GET /api/example/page?pageNo=1&pageSize=10&name=测试

# 带精确过滤
GET /api/example/page?pageNo=1&pageSize=10&status=1&type=2

# 自定义排序
GET /api/example/page?pageNo=1&pageSize=10&orderField=sort&orderType=asc

# 指定返回字段
GET /api/example/page?pageNo=1&pageSize=10&fields=id,name,status
```

## 返回结构

```json
{
    "code": 0,
    "ok": true,
    "msg": "操作成功",
    "data": {
        "records": [
            { "id": 1, "name": "测试", "status": 1, "statusText": "启用" }
        ],
        "total": 100,
        "size": 10,
        "current": 1,
        "pages": 10
    }
}
```

## 参数转换

前端使用 camelCase，后端自动转换为 snake_case。排除项（pageNo、pageSize、orderField、orderType、fields）不参与转换。详见 [横切机制 - 驼峰/下划线转换](/zh/architecture/cross-cutting.html)。

## 排序字段

| 前端传参 | 后端处理 | SQL |
|---------|---------|-----|
| `orderField=createTime&orderType=desc` | 转为 `create_time` | `ORDER BY create_time DESC` |
| 不传 | 使用 Logic 默认排序 | 按 `pageOrderBy` 配置 |