# API 分页设计：offset/limit 与游标分页

> 讲清 API 分页契约：offset/limit 与游标的取舍、稳定排序与兜底键、签名游标、页大小上限、has_more 与 Link 响应头、一致性与缓存，并给出验证清单。

**快速答案:** 分页是一份接口契约：全序、每页上限、续页令牌和结束信号缺一不可。offset/limit 简单、可跳页，但写入时会漂移、深分页会变慢；游标分页记录上一页最后一条的排序键，只要排序键唯一且不可变就稳定，但游标必须不透明、签名，并与过滤和排序绑定。

## 核心要点

- 列表接口要承诺四件事：全序、实际页大小、续页令牌和诚实的结束信号；任何一项含糊，都会带来重复、遗漏或卡住的客户端。
- offset/limit 适合小规模、可跳页的集合；游标分页适合信息流、导出、同步任务，以及任何会在读取过程中增长或变化的数据集。
- 每种排序都需要唯一且不可变的兜底键，例如主键；游标的比较条件和数据库索引必须与排序完全一致。
- 把游标当作不透明、签名、带版本和过期时间、并绑定租户与过滤排序的状态；页大小和 offset 要在进入数据库之前校验。
- 多取一行计算 has_more，正文链接与 Link 响应头由同一个函数生成，分页读取保持幂等，只缓存内容真正稳定的页面。

---

API 的一页是一个承诺：下一次请求会从上一页结束的位置继续。这个承诺由四部分组成——全序、每页大小、续页令牌和结束信号——分页事故大多源于其中某一项没有说清。插入一行后表格重复显示、同步任务悄悄漏掉一张发票、导出在九万行处卡住，往往是同一个缺陷在不同客户端上的表现。

令牌的形态还决定深分页是一次索引定位，还是扫描并丢弃上百万行。下面的设计决定这个承诺能否在并发写入、重试和压力下成立。

## 分页是接口契约，不是查询细节

每个列表接口都应该说明自己保证什么。四个决定构成契约。第一，集合存在全序；除非底层数据变化，否则多次请求的顺序不变。第二，服务端选定实际页大小，并说明默认值和上限。第三，响应携带续页令牌，精确指向最后一条之后的位置。第四，响应说明是否还有数据，最好直接给出下一页链接。

多数接口只写了页大小，其余部分靠客户端在生产事故中摸索：顺序在两次请求间翻转、limit 被悄悄截断、next 链接返回空页、修改过滤条件后游标不能用。有用的契约还要说明并发写入时的行为。承诺不重不漏，需要快照或基于位置的令牌；只承诺尽力而为也可以，但必须写清楚，让客户端能够补偿。

## offset/limit 与游标分页

offset/limit 是熟悉的形式：`?offset=40&limit=20` 或 `?page=3&per_page=20`。它直接对应 SQL 的 `OFFSET` 和 `LIMIT`，可以跳到任意页，也天然配合总数统计。问题会随数据量增长而出现：数据库必须先走过并丢弃 `offset` 行，延迟随深度线性增长；当前页之前一旦插入新行，后面所有行的位置都会下移，下一页因此重复一条，删除时则跳过一条。

游标分页用基于值的位置替代算术位置。令牌记录本页最后一条的排序键，下一次查询变成 `WHERE (created_at, id) < (:created_at, :id) ORDER BY created_at DESC, id DESC LIMIT :n`。数据库直接定位到索引位置，成本随深度基本不变，游标之前的插入或删除也不会移动边界。代价是只能顺序读取、令牌更复杂，并且没有天然页码。

| 维度 | offset/limit | 游标 |
| --- | --- | --- |
| 访问方式 | 可跳到任意页 | 只能前后顺序读取 |
| 深分页成本 | 随 offset 增长 | 索引定位加一页读取 |
| 并发插入 | 边界处重复或遗漏 | 边界不漂移 |
| 并发删除 | 跳过行 | 被删行直接消失 |
| 总数 | 天然支持，但要单独查询 | 尽量避免或只给估算 |
| 客户端状态 | 小整数 | 不透明令牌 |
| 修改过滤或排序 | 从第一页重新查询 | 游标失效 |
| 缓存行为 | URL 可缓存，但内容会移动 | 基数高，很少共享 |
| 适用场景 | 后台表格、小型静态集合 | 信息流、导出、同步、大数据集 |

选择依据是访问模式，而不是流行度。需要跳到第 40 页并显示总数的后台表格，在表小或过滤条件足够精确时适合 offset。信息流、导出、同步任务、审计日志以及任何可能无限增长的数据集应该用游标。混合接口可以同时接受小偏移的 `page` 和遍历用的 `cursor`，但必须拒绝两者混用并写明限制；不要根据集合大小悄悄切换模式，客户端会依赖它第一次看到的行为。

## 稳定全序与兜底排序键

没有 `ORDER BY` 的 offset 分页行为未定义；没有全序的游标分页不安全。`ORDER BY created_at DESC` 不是全序，因为时间戳会冲突。两行时间相同时，数据库可以按任意顺序返回，而且顺序可能随执行计划、只读副本或新索引而变化。分页边界落在相等值之间，下一页就会重复一行、丢掉另一行。

增加唯一且不可变的兜底键：`ORDER BY created_at DESC, id DESC`。游标必须同时携带两个值，比较条件必须与索引匹配，数据库支持时优先用行构造器 `WHERE (created_at, id) < (:created_at, :id)`，否则展开成 `OR` 比较。`(created_at, id)` 上的索引让数据库定位后顺序读取；混合方向如 `created_at DESC, id ASC` 需要完全对应的索引和比较条件。

兜底键绝不能变化。`updated_at`、状态、评分和热度会在变化时把行从一页移到另一页，即使有游标也会重新引入重复和遗漏。序列主键、UUIDv7 或 ULID 稳定、唯一，而且通常有索引。显式定义空值位置，例如 `NULLS LAST`，因为不同数据库的默认行为不一致；大小写不敏感或按语言排序的文本排序规则可能把两个不同字符串视为相等，唯一兜底键仍然能确定顺序。

## 不透明游标与签名状态

游标是位置，不是标识符。对客户端来说它应当是不透明字符串，即使内部只是可读的 base64。不透明带来三点好处：服务端可以更换编码而不破坏兼容；客户端无法伪造有效游标；自增数据库 ID 不会出现在 URL 中，避免被枚举，也减少客服排查时的混淆。

实用的载荷是一段紧凑 JSON：版本、排序键值、方向、规范化过滤与排序的哈希、租户或用户范围，以及签发时间和过期时间。用 base64url 编码，再用服务端持有的密钥做 HMAC-SHA256 签名。下一次请求先验证签名再解析，检查过期时间，并比对过滤哈希和范围。不匹配时返回 `400` 和稳定错误码，而不是从另一个查询里随便切一页。

签名保护完整性，不保护机密性。拿到游标的人都能解开 base64，所以除非用认证加密，不要把邮箱、搜索词或完整过滤对象放进载荷。令牌要小：它走查询字符串，必须经受代理、日志和复制粘贴。无状态签名游标不需要存储，扩展容易，但无法撤销，也不能绑定数据库快照；服务端游标两者都能做到，代价是存储和过期管理。给格式加版本号，让旧游标在发布后干净地失败。

```http
GET /v1/invoices?limit=2&cursor=eyJ2IjoxLCJjcmVhdGVkX2F0IjoiMjAyNi0xMS0xN1QwODowMDowMFoiLCJpZCI6Imludl8xMDI0In0 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "items": [
    { "id": "inv_1023", "created_at": "2026-11-17T08:00:00Z", "total": 4200 },
    { "id": "inv_1022", "created_at": "2026-11-17T07:59:58Z", "total": 1900 }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJjcmVhdGVkX2F0IjoiMjAyNi0xMS0xN1QwNzo1OTo1OFoiLCJpZCI6Imludl8xMDIyIn0"
}
```

上面的响应返回两张发票和一个指向最后一条的游标。下一次请求带上这个游标和相同的 `limit`；服务端验证签名，还原出 `(2026-11-17T07:59:58Z, inv_1022)`，从该位置之后继续。

## 每页大小：默认值、上限与校验

没有页大小上限的接口，等于在等一个带循环的客户端把服务打挂。序列化上百万行会占用应用内存、长时间持有数据库连接、塞满网络，而且往往在工作做完之后才超时。设定默认值（常见为 20 到 100 行）和硬上限，然后决定超限行为。对 `limit=100000` 返回 `400` 是最清晰的契约；只有在响应回显实际 limit 且 `has_more` 仍然正确时，静默截断到 100 才可以接受。

校验完整的取值空间：零、负数、非整数、重复参数和荒谬值。offset 也要设上限，例如 10,000，并在超限时返回 `400`，提示客户端改用游标。按字节而不只按行数衡量：宽行、嵌套展开和二进制字段会让 20 条数据比 1,000 条窄记录还大，因此要单独限制展开资源。OWASP 把不受限的资源消耗列为 API 主要风险，正是因为这类上限经常缺失。

每个响应都回显实际 `limit` 和返回条数。截断因此可见，客服也有具体数字可问。页大小还影响速率限制：默认 10 会把一次请求拆成十次，默认 1,000 又会惩罚移动客户端。测量载荷大小和延迟，再选一个适合中位记录的默认值。

## has_more、next/prev 链接与 Link 响应头

`has_more` 应该算出来，而不是猜。多取 `limit + 1` 行，只返回前 `limit` 条，用是否多出那一行来决定 `has_more`。这多读一行，却避免在大表上做 `COUNT(*)`。如果界面要显示“4,382 条中的第 1–20 条”，总数仍然有用，但它应当是可选字段；来自统计信息时还要标明是估算。

下一页游标是本页最后一条的排序键，绝不是结果集里的下标。只有 `has_more` 为真时才返回 `next_cursor`；只有接口支持反向遍历时才返回 `prev_cursor`，并由第一条推导。返回一个空页的链接既浪费往返，也说明契约有问题。

`Link` 响应头让 HTTP 客户端不必解析正文就能拿到同样的信息：`Link: <https://api.example.com/v1/invoices?limit=20&cursor=...>; rel="next"`。使用绝对 URL，保留所有过滤和排序参数，对游标做 URL 编码，只在有意义时输出 `rel="prev"`、`rel="first"` 和 `rel="last"`。游标接口通常无法低成本实现 `last`，那就省略，不要伪造。正文链接和响应头链接必须由同一个函数生成，两者不一致是常见 bug。空结果或最后一页返回 `200`、空 `items` 数组和 `has_more: false`。

除非计数很便宜或明确标注为近似值，否则不要暴露 `total`。在大规模过滤集合上做精确总数，成本可能超过这一页数据本身。

## 过滤、排序与游标失效

游标只对产生它的查询有效。客户端加上 `status=paid` 却复用为全部状态创建的游标时，基于值的位置仍然指向旧排序，服务端会返回一段看起来合理的任意切片。把规范化后的过滤和排序哈希绑进游标，下一次请求重新计算并比对，不匹配就返回 `cursor_query_mismatch` 之类的明确错误。哈希前要统一参数顺序、大小写和编码，让等价查询得到相同哈希。

排序字段必须走白名单。接受客户端传入列名会招来 SQL 注入，也会产生无法走索引的全表排序。把公开的排序名映射到已知列和方向，拒绝其他值，并在文档里写明默认排序。排序改变即遍历重置：客户端从没有游标的第一页重新开始。

搜索是最难的情况。相关性分数会随索引合并而变化，单靠 `ORDER BY score DESC` 并不稳定；要配合唯一兜底键，并告知客户端顺序可能变化。如果稳定遍历比最新排名更重要，就把快照或 `as_of` 时间戳固定进游标。时间范围过滤同理：第一次请求时设定上界，避免新建行在遍历途中进入结果集。

## 深 offset、一致性与幂等分页读取

深 offset 即使走索引也很贵。`OFFSET 100000 LIMIT 20` 要求数据库先定位、计数并丢弃 100,000 行，然后才返回二十条；工作量随偏移线性增长，缓冲缓存被拖累，执行计划甚至可能放弃索引。keyset 分页把同一请求变成一次索引定位加二十次读取，数据量增长时仍然平稳。如果为了兼容保留 offset 分页，就限制最大偏移，并把更深的请求引导到游标或导出任务。

游标分页消除的是边界漂移，不是所有一致性问题。游标之前的插入在遍历中不可见，因为它已经被越过；游标之后的插入会出现在后面的页里。两者都不会重复。游标之后的删除只是少一条；删除游标本身那一行也不会破坏查询，因为比较用的是值，不是行是否存在。更新不同：排序键一旦变化，行可能从游标后面移到前面，或者反过来。这就是排序键必须不可变的原因。

产品需要真正快照时，要显式实现。把快照时间戳或事务标识放进游标，并在每次分页查询里加上 `created_at <= :snapshot`；或者让遍历跑在可重复读事务、物化导出上。写清成本和过期时间。没有快照就只能承诺尽力而为：插入和删除不会造成重复，但排序键更新可能移动行。

分页读取应当幂等。数据未变时，相同游标和参数的 `GET` 必须返回同一页，重试必须安全。不要在服务端消费游标；超时后的重试不应该收到 `409`。如果游标必须一次性使用，就返回幂等键并写明行为。

缓存也遵循同一份契约。没有游标的第一页被许多客户端共享，可以设置较短 TTL；游标页基数高，且随集合变化，很少命中共享缓存。用户范围的页面标记 `private` 或 `no-store`，条件读取用 `ETag`，CDN 的缓存键绝不能漏掉游标或过滤参数。URL 里的游标可能通过日志和 Referer 泄露，所以载荷里不要放敏感值。

## 带明确通过标准的验证清单

准备一张包含重复排序键、遍历期间插入和删除的行、以及至少一个分页边界的表来测试。验证是一串真实请求，而不是序列化器的单元测试。

```bash
# 1. 取第一页并保存游标。
curl -sS 'https://api.example.com/v1/invoices?limit=2' -o page1.json

# 2. 在边界之前插入一行，再用旧游标取下一页。
curl -sS 'https://api.example.com/v1/invoices?limit=2&cursor=...' -o page2.json

# 3. 篡改游标，确认被干净地拒绝。
curl -sS -o /dev/null -w '%{http_code}\n' \
  'https://api.example.com/v1/invoices?cursor=not-a-real-cursor'

# 4. 请求超大页，检查实际生效的 limit。
curl -sS 'https://api.example.com/v1/invoices?limit=100000' | head -c 300
```

[HTTP 请求工作台](/tools/http-request)用精确的请求头重放这些调用；[JSONPath 查询器](/tools/jsonpath)从抓到的响应里提取 `items[].id` 和 `has_more`；[JSON 格式化工具](/tools/json-formatter)格式化每一页，让顺序问题和重复 ID 一眼可见。

只有下表每一行都成立，才算通过：

| 检查项 | 验证方式 | 通过标准 |
| --- | --- | --- |
| 全序 | 在无写入时连续两次请求同一页 | ID 与顺序完全一致 |
| 兜底键 | 插入共享边界时间戳的多行 | 遍历中每行只出现一次，没有遗漏 |
| offset 漂移 | 在边界前插入一行并用 offset 翻页 | 出现重复；游标路径不重复 |
| 游标完整性 | 改动令牌中的一个字符 | 返回 `400` 和稳定错误码，不返回数据 |
| 游标作用域 | 用不同过滤或排序复用游标 | 返回 `400 cursor_query_mismatch`，不返回部分切片 |
| 页大小 | 发送 `limit=0`、`limit=-1`、`limit=100000` | 返回 `400` 或有文档的截断，并回显实际 limit |
| has_more | 取倒数第二页和最后一页 | 先 `true` 后 `false`，最后一页没有 next 链接 |
| Link 响应头 | 用 `curl -sSI` 检查响应头 | 绝对 `rel="next"` URL、游标已编码、过滤参数保留 |
| 幂等重试 | 用同一个游标请求两次 | 两次返回同一页和相同状态码 |
| 缓存策略 | 分别请求登录态页面和公开首页 | 私有页面 `no-store`，公开页面有明确 TTL |

十项检查通过九项，仍然可能在生产里重复行。真正要紧的失败都发生在边界，所以要显式测试边界。

## 常见错误与生产规则

代价高昂的错误基本可以预测：

- 深分页继续用 `OFFSET`，却把延迟归咎于数据库。
- 只按 `created_at` 排序，假设相同时间戳的顺序稳定。
- 把连续数据库 ID 直接当游标，招来枚举。
- 完全不签名，客户端可以伪造位置或别的租户范围。
- 不绑定过滤哈希，游标被悄悄套用到另一个查询。
- 接受无上限的 `limit` 或 offset，直到事故才发现。
- 最后一页仍返回 `has_more: true`，或 next 链接取不到任何数据。
- 每一页都用 `COUNT(*)` 计算 `total`。
- 在服务端消费游标，超时重试因此失败。
- 公开缓存游标页，或 CDN 缓存键漏掉游标。

防止这些问题的规则很短。先定义排序契约：唯一且不可变的排序键，以及匹配的索引。小规模、可跳页的集合用 offset，会增长或变化的集合用游标。游标必须不透明、签名、带版本、限定作用域并会过期。在边缘校验页大小和 offset，多取一行判断 `has_more`，链接统一由一个函数生成。把分页读取当作幂等 `GET`，写清一致性保证，只缓存稳定的内容，并在发布前用真实插入和删除验证边界行为。

## 常见问题

### API 应该用 offset/limit 还是游标分页？

小规模或变化缓慢、需要跳到任意页并显示总数的集合适合 offset/limit，例如后台表格。信息流、导出、同步、审计日志，以及深 offset 昂贵或并发写入会移动页边界的集合，应该使用游标分页。

### 为什么在变化的表上翻页时会出现重复或漏行？

当前 offset 之前插入一行，后面所有行都会下移，下一页就会重复一条；删除一行则会让后面的行上移，从而漏掉一条。游标分页比较排序键的值而不是行数，只要排序键唯一、不可变且有索引，就不会发生边界漂移。

### 游标可以直接用数据库 ID 吗？

可以，但连续 ID 会招来枚举，也把编码方式永久固定。更好的做法是不透明令牌，里面携带完整排序键、版本、过滤哈希、作用范围和过期时间，并用 HMAC 签名，使客户端无法伪造位置或读取其他租户的数据。

### API 应该如何表示还有下一页？

多取一页之外的一行，只返回请求的条数，并用是否多出这一行来设置 has_more。只有 has_more 为真时才给出 next 游标，同时用同一组值生成 rel=next 的 Link 响应头，避免正文和响应头不一致。

### 每页应该多大，超过上限会怎样？

默认值取你能从容服务的响应中位数，常见是 20 到 100 行，并设置硬上限。超限请求应返回有文档的 400，或者截断并在响应中回显实际 limit；绝不能让客户端请求无上限的页大小或 offset。

## 参考资料

- [Stripe：分页](https://docs.stripe.com/api/pagination)
- [Google Cloud API 设计：列表分页](https://cloud.google.com/apis/design/design_patterns#list_pagination)
- [Microsoft REST API 指南](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md)
- [OWASP API 安全 Top 10](https://owasp.org/API-Security/editions/2023/en/0x11-t10/)

---

- Canonical: https://www.jsonmind.com/zh-CN/guides/api-pagination-design
- Locale: zh-CN
- Published: 2026-11-17
- Updated: 2026-11-17
- Tools: http-request, jsonpath, json-formatter