65 lines
1.8 KiB
Markdown
65 lines
1.8 KiB
Markdown
# 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` 配置 | |