pagination

Pagination Skill — 分页设计

何时使用

• 设计 list API（任何返回多条记录的端点）
• 排查"翻到第 1000 页超慢" / "数据漏 / 重复"
• 需要无限滚动 UI（feed / timeline）
• Elasticsearch / Mongo 深分页性能问题
• GraphQL connection 规范实现

一、两大流派

Offset/Limit（最熟悉，但坑最多）

GET /users?offset=0&limit=20
GET /users?page=1&page_size=20

优点：直观 / 跳页方便（"第 5 页"）/ 显示总数 缺点：

1. 深分页慢：OFFSET 100000 数据库要扫描丢弃 10 万行
2. 数据漂移：翻页期间有新数据插入 → 重复或漏数据
3. 不稳定排序：相同排序值的多行顺序不定 → 翻页错乱

Cursor（推荐用于 feed / 大数据集）

GET /users?cursor=eyJpZCI6MTIzNDV9&limit=20

优点：性能稳定（O(1) 不论第几页）/ 无漂移问题 缺点：不支持跳页 / 不显示总数 / 实现稍复杂

二、Cursor 实现模式

1. 简单单字段 cursor

-- 第一页
SELECT * FROM users ORDER BY id LIMIT 20

-- 后续页：用最后一条 ID 当 cursor
SELECT * FROM users WHERE id > $cursor ORDER BY id LIMIT 20

cursor = 最后一条的 id（base64 编码后给客户端）。

2. 复合键 cursor（按时间倒序）

SELECT * FROM posts
WHERE (created_at, id) < ($cursor_ts, $cursor_id)
ORDER BY created_at DESC, id DESC
LIMIT 20

为什么加 id 做 tie-breaker：相同 created_at 的多条不加 id 会乱序 / 翻页漏。

3. cursor 编码

// 服务端
function encodeCursor(row) {
  return Buffer.from(JSON.stringify({
    ts: row.created_at.toISOString(),
    id: row.id,
  })).toString('base64url')
}

function decodeCursor(s) {
  return JSON.parse(Buffer.from(s, 'base64url').toString('utf8'))
}

安全：不要让客户端伪造 cursor 跳过权限。可以 HMAC 签名 / 加盐：

const cursor = base64({ ts, id, sig: hmac(ts + id, secret) })

或者只暴露不可猜的 ID（UUID v7）— 让 cursor 自然失效。

4. 双向分页

GET /posts?after=cursor1&limit=20    # 下一页
GET /posts?before=cursor1&limit=20   # 上一页

-- after
WHERE (ts, id) < ($after.ts, $after.id) ORDER BY ts DESC, id DESC

-- before（注意结果集要再反转）
WHERE (ts, id) > ($before.ts, $before.id) ORDER BY ts ASC, id ASC
-- 然后 reverse() 给客户端

三、Keyset Pagination（SQL 索引利用）

-- ❌ OFFSET 慢
SELECT * FROM users ORDER BY created_at DESC OFFSET 100000 LIMIT 20;
-- 扫 100020 行丢弃 100000

-- ✅ Keyset（cursor 模式）
SELECT * FROM users
WHERE (created_at, id) < ('2024-01-01', 12345)
ORDER BY created_at DESC, id DESC
LIMIT 20;
-- 利用 (created_at, id) 索引直接 seek 到位置，扫 20 行