import{_ as i,o as a,c as t,a2 as h}from"./chunks/framework.BbmSSMjL.js";const g=JSON.parse('{"title":"12.2 分页查询规范","description":"","frontmatter":{},"headers":[],"relativePath":"zh/standards/pagination.md","filePath":"zh/standards/pagination.md"}'),n={name:"zh/standards/pagination.md"};function k(p,s,l,e,d,r){return a(),t("div",null,[...s[0]||(s[0]=[h(`

12.2 分页查询规范

概述

所有分页接口遵循统一的参数命名和返回结构，确保前后端一致性。详细机制见 8.3 分页查询规范。

请求参数

参数	类型	默认值	说明
`pageNo`	number	1	页码（最小为 1）
`pageSize`	number	20	每页条数（1~100，超出自动限制）
`orderField`	string	-	排序字段（camelCase，如 `createTime`）
`orderType`	string	`desc`	排序方向（`asc` / `desc`）
`fields`	string	-	返回字段（逗号分隔，如 `id,username,status`）
其他参数	-	-	按 Service 中 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）不参与转换。详见横切机制 - 驼峰/下划线转换。

排序字段

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

排序白名单

orderField 只在 pageOrderBy 默认字段 ∪ orderFieldAllow 的并集内生效，不在白名单内的字段直接忽略（防 SQL 注入）。开放新排序字段请配置 orderFieldAllow。

`,13)])])}const E=i(n,[["render",k]]);export{g as __pageData,E as default};

12.2 分页查询规范 ​

请求参数 ​

请求示例 ​

返回结构 ​