签入版本

EasyGoAdmin_Gin_AntdVue/zh/standards/pagination.md

@@ -1,65 +1,41 @@
 # 12.2 分页查询规范
 
-:::tip 概述
-所有分页接口遵循统一的参数命名和返回结构，确保前后端一致性。
+:::tip 必须遵守
+列表查询一律用分页契约：请求内嵌 PageReq，响应为 PageData 五字段。禁止自造分页参数名或响应结构。
 :::
 
-## 请求参数
+## 契约
 
-| 参数 | 类型 | 默认值 | 说明 |
-|------|------|--------|------|
-| `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
+```text
+请求：pageNo（默认 1）/ pageSize（默认 10，上限 500）
+响应：records / total / size / current / pages
 ```
 
-## 返回结构
+## 服务端规约
 
-```json
-{
-    "code": 0,
-    "ok": true,
-    "msg": "操作成功",
-    "data": {
-        "records": [
-            { "id": 1, "name": "测试", "status": 1, "statusText": "启用" }
-        ],
-        "total": 100,
-        "size": 10,
-        "current": 1,
-        "pages": 10
-    }
-}
-```
+- 请求结构内嵌 `dto.PageReq`，不手写 pageNo/pageSize 字段
+- 分页经 ModuleSpec.Page 委托（自动兜底与组壳）
+- records 空时输出 `[]`（NewPageData 保证）
+- 深翻页由 pageSize 上限兜底；特殊大导出走 Export 而非超大分页
 
-## 参数转换
+## 前端规约
 
-前端使用 camelCase，后端自动转换为 snake_case。排除项（pageNo、pageSize、orderField、orderType、fields）不参与转换。详见 [横切机制 - 驼峰/下划线转换](/zh/architecture/cross-cutting.html)。
+- 分页组件绑定 pageNo/pageSize，变更即重查
+- 筛选变化回到第 1 页
+- 判空按 `records.length`（不判 null）
 
-## 排序字段
+## List（全量）的边界
 
-| 前端传参 | 后端处理 | SQL |
-|---------|---------|-----|
-| `orderField=createTime&orderType=desc` | 转为 `create_time` | `ORDER BY create_time DESC` |
-| 不传 | 使用 Logic 默认排序 | 按 `pageOrderBy` 配置 |
+下拉数据源等小数据量用 List + limit 上限；**任何面向页面表格的数据必须走 Page**。导出用 Export（服务端流式写出），不以"大 pageSize 分页"替代。
+
+## 反例
+
+| 反例 | 问题 |
+|---|---|
+| 自造参数 offset/limit/size 混用 | 与基座、生成器、前端组件不兼容 |
+| 响应只回数组不回 total | 前端无法渲染分页条 |
+| pageSize 不设上限 | 一次拉爆内存 |
+
+## 相关
+
+- [8.3 分页查询规范](/zh/api-spec/pagination.html)