签入版本

2026-09-29 10:14:04 +08:00
parent 3e5fc01124
commit d6b552103d
1664 changed files with 298944 additions and 0 deletions
@@ -0,0 +1,65 @@
+# 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` 配置 |