REST API 分页设计与边界处理:从 offset 到游标

文章目录

问题从哪里来

分页接口通常是最早写、最晚被认真检查的一类接口。它的基础形态很简单:客户端传页码和每页条数,服务端拼一条带 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 排序和索引使用的处理并不完全相同,落地时应结合实际执行计划验证。