问题从哪里来
分页接口通常是最早写、最晚被认真检查的一类接口。它的基础形态很简单:客户端传页码和每页条数,服务端拼一条带 LIMIT / OFFSET 的查询。但当数据量增长、列表被高频写入、客户端开始做无限滚动之后,下面这些问题会陆续出现:
- 每页条数没有上限,一次请求拉走几十万行,数据库和网络同时承压。
page很大时OFFSET很深,数据库要先扫描并丢弃前面所有行,越翻越慢。- 翻页过程中有记录被插入或删除,用户看到重复条目或漏掉条目。
- 排序字段不唯一(例如只按
created_at排序),同一时间的多条记录顺序不稳定,翻页结果错乱。 - 参数是非数字、负数、超大值时,接口返回 500 或静默纠正成默认值,调用方无法感知自己的错误。
- 为了返回
total每次都执行一次COUNT(*),把便宜的分页变成昂贵查询。
这些问题的共同点是:它们都不在“正常路径”上,而分页的正确性恰恰由边界决定。下面按“先定契约,再选方案,最后补边界”的顺序展开。
先定分页契约
在写 SQL 之前,先把接口语义固定下来,可以省掉后面大量争论。
命名与语义。 二选一并全站统一:
- 偏移式:
page(从 1 开始)+page_size,或limit+offset(从 0 开始)。两者混用是常见事故来源。 - 游标式:
limit+cursor,cursor对客户端不透明。
排序必须稳定。 任何分页查询的排序键组合都应当是唯一的,常见做法是在业务排序字段后追加主键:ORDER BY created_at DESC, id DESC。没有这个兜底,即使 SQL 写对了,翻页也会随机错位。
服务端强制上限。 默认值(例如 20)和最大值(例如 100)都由服务端决定,客户端传再大也截断或报错,不能交给调用方自觉。
非法参数明确报错。 返回 400 并说明哪个参数不合法,比静默改成默认值更利于排查。
判断是否还有下一页。 有两种做法:多取一条(LIMIT n+1)看是否够数;或者返回 next_cursor / next_offset,为空表示到底。不要依赖“返回条数小于 limit 就说明没有下一页”这种隐式约定而不写进文档。
偏移分页:实现与边界
偏移分页适合数据量可控、需要跳页的场景(后台管理列表、搜索结果页)。
参数校验先落地:
DEFAULT_LIMIT = 20
MAX_LIMIT = 100
MAX_OFFSET = 10_000
def parse_limit(raw):
if raw is None:
return DEFAULT_LIMIT
try:
value = int(raw)
except (TypeError, ValueError):
raise BadRequest("limit 必须是整数")
if value < 1 or value > MAX_LIMIT:
raise BadRequest(f"limit 需在 1 到 {MAX_LIMIT} 之间")
return value
def parse_offset(raw):
if raw is None:
return 0
try:
value = int(raw)
except (TypeError, ValueError):
raise BadRequest("offset 必须是整数")
if value < 0 or value > MAX_OFFSET:
raise BadRequest("offset 超出允许范围,请使用游标分页")
return value对应查询:
SELECT id, title, created_at
FROM articles
WHERE status = 'published'
ORDER BY created_at DESC, id DESC
LIMIT :limit OFFSET :offset;需要为 (status, created_at, id) 建立复合索引,让过滤、排序和分页共用同一棵索引,避免额外的文件排序。
边界处理要点:
offset超过总数时,返回空数组和has_more: false,HTTP 状态仍是 200。把“没有更多数据”当成 404 会让客户端逻辑变形。offset设上限并给出明确错误,而不是让深分页悄悄拖慢数据库。total是可选项。每次请求都COUNT(*)成本很高,可改为只在第一页返回、用估算值,或干脆不提供,让客户端依据has_more判断。- 不要同时接受
page和offset,如果历史原因必须兼容,就以其中一个为准并在文档中写清楚。
游标分页:稳定且可扩展
游标(键集)分页不再计算偏移,而是记住“上一页最后一条记录的位置”,从该位置继续往后取。它的查询代价与页码无关,也不会因为中途插入数据而整体错位。
SELECT id, title, created_at
FROM articles
WHERE status = 'published'
AND (created_at < :last_created_at
OR (created_at = :last_created_at AND id < :last_id))
ORDER BY created_at DESC, id DESC
LIMIT :limit;这里把行比较展开写,而不是使用 (created_at, id) < (:c, :i) 这样的行构造器形式,是为了让索引使用更可预期;具体执行计划仍以实际数据库版本为准,应当用 EXPLAIN 确认。
游标本身建议编码成不透明字符串,这样以后更换排序字段或增加过滤条件时不必改客户端:
import base64
import json
def encode_cursor(created_at, last_id):
payload = {"t": created_at.isoformat(), "i": last_id}
raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")
return base64.urlsafe_b64encode(raw).decode("ascii").rstrip("=")
def decode_cursor(cursor):
try:
padding = "=" * (-len(cursor) % 4)
raw = base64.urlsafe_b64decode(cursor + padding)
payload = json.loads(raw)
return payload["t"], payload["i"]
except Exception:
raise BadRequest("cursor 无效")边界处理要点:
- 游标要与过滤条件和排序方式绑定。客户端改了筛选条件却沿用旧游标,应当报 400 或忽略游标从头开始,不能默默返回语义错误的结果。
- 游标解析失败一律 400,不要回退到第一页,否则调用方的分页循环可能永远停不下来。
- 时间字段精度要足够。若
created_at只精确到秒,同一秒内多条记录必须靠id兜底,这也是排序键要包含主键的原因。 - 参与排序的字段为
NULL时,比较语义在各数据库间存在差异,最好在建模阶段就避免排序列可空,或明确规定NULL的排序位置。 - 游标不天然防篡改。若游标里包含敏感信息或需要防止越权,应在服务端签名或加密,而不是只做 Base64。
响应结构
不管采用哪种方案,把分页元数据放进独立字段,比散落在顶层更容易演进:
{
"items": [],
"page_info": {
"limit": 20,
"has_more": true,
"next_cursor": "eyJ0IjoiMjAyNC0wNS0wMVQxMDowMDowMCIsImkiOjEyMzQ1fQ"
}
}偏移式则可返回 offset、limit、has_more,需要时再加 total。字段命名一旦对外发布就应当保持稳定,新增字段优于修改语义。
常见错误
- 只按时间排序。 时间相同的记录顺序不稳定,翻页出现重复或遗漏,必须追加主键。
- 用返回条数推断结束。 恰好最后一页是满页时,客户端会多发一次空请求;有
has_more更明确。 - 把 400 写成 500。 参数不合法是调用方问题,状态码要能区分。
- 无限滚动配偏移分页。 用户越往下滑越慢,且新数据插入会导致内容重复出现。
- 游标里只存偏移量。 那只是把偏移分页换了个名字,深分页问题依旧。
- 忽略并发写入。 即使使用游标,翻页期间的数据变动仍可能造成重复条目,客户端应按主键去重。
- 导出场景直接复用列表分页。 大批量导出应走游标或按主键区间分批,并配合流式输出。
适用边界
偏移分页实现简单、支持任意跳页,适合数据量在可控范围内、以人工浏览为主的场景。当 OFFSET 需要扫描的行数达到数万级以上时,其代价会明显上升,此时应限制最大页数或改用游标。
游标分页的代价是无法直接跳到第 N 页,只能顺序向后,也不方便展示“共 X 页”。对于无限滚动、消息流、数据导出这类顺序消费的场景,它是更合适的选择。
如果产品同时要求“任意跳页”和“海量数据”,通常需要在产品层面妥协:限制可跳转的页数、改用基于条件的筛选而非页码导航,或者接受估算总数。这不是接口层能单独解决的问题。另外,以上讨论针对常规关系型数据库的分页语义,不同数据库对行比较、NULL 排序和索引使用的处理并不完全相同,落地时应结合实际执行计划验证。