---
name: api-pagination
when: >-
  分页查询接口, 分页, 翻页, PageRequest, pagination, 列表查询, 数据列表, 页码, pageSize, pageNo,
  查询列表
scope:
  - backend
products:
  - '*'
id: ka-pattern-api-pagination
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - 分页查询接口
  - 分页
  - 翻页
  - PageRequest
  - pagination
  - 列表查询
  - 数据列表
  - 页码
  - pageSize
  - pageNo
  - 查询列表
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 必须使用数据库分页查询（LIMIT/OFFSET），禁止内存 subList 分页
- 必须限制最大 pageSize（不超过 100）
- 排序字段必须使用白名单校验，禁止直接拼接用户输入
- 深分页（page > 1000）必须使用游标分页替代 OFFSET
- 分页响应必须包含 total、page、size、totalPages 字段
- 深分页（offset > 10000）必须使用游标分页或子查询优化，禁止直接 OFFSET
- 分页查询禁止使用 SELECT *，必须指定所需字段
- 排序字段必须是索引列，禁止对非索引列排序导致全表扫描
- 前端分页控件必须显示总条数和页码跳转

## 验收项
- [AC-01] page >= 1 且 1 <= size <= 100
- [AC-02] 使用数据库分页而非内存分页
- [AC-03] 响应含 total/page/size/totalPages
- [AC-04] 排序字段白名单校验
- [AC-05] 深分页有优化策略
- [AC-06] 排序字段使用索引列
- [AC-07] 前端有页码跳转
