API 设计 / 系统课时
让 Cursor 分页落到数据库
让 Cursor 分页落到数据库
Cursor 分页要可扩展,关键是让游标条件直接转成可利用索引的数据库范围扫描。本节以 PostgreSQL 为例,用稳定复合排序键、匹配索引和 LIMIT first + 1 实现 Keyset Pagination。
学习目标
- 用唯一且稳定的复合排序键定义游标位置。
- 把
after游标翻译为数据库范围条件并命中索引。 - 正确生成
endCursor与hasNextPage,处理并发写入和边界情况。
用稳定排序键定义游标边界
单独按 created_at DESC 排序并不稳定,因为多行可能拥有相同时间戳。可靠做法是追加唯一键作为 tie-breaker,例如 ORDER BY created_at DESC, id DESC,并让 Cursor 同时携带这两个值。下一页不是“跳过前 N 行”,而是从 (created_at, id) 这个边界继续向后扫描。

Cursor 对客户端应保持不透明。服务端可以把排序元组编码成 Base64URL 或签名后的令牌,但解码后必须校验字段数量、类型和版本。更重要的是,游标内的值必须与当前查询的排序方式、筛选条件和租户范围一致,否则同一个 Cursor 不能安全复用。
用复合索引执行 Keyset 查询
下面的 PostgreSQL 主示例创建一组固定数据,并展示第一页的多取一行以及以第一页末尾记录为边界读取下一页。页面大小设为 2,因此 SQL 读取 3 行来判断是否还存在下一页。
SET TIME ZONE 'UTC';
CREATE TEMP TABLE posts (
id bigint PRIMARY KEY,
created_at timestamptz NOT NULL,
title text NOT NULL
);
INSERT INTO posts (id, created_at, title) VALUES
(1, '2026-08-24 09:59:00+00', 'A'),
(2, '2026-08-24 10:00:00+00', 'B'),
(3, '2026-08-24 10:00:00+00', 'C'),
(4, '2026-08-24 10:01:00+00', 'D');
CREATE INDEX idx_posts_cursor
ON posts (created_at DESC, id DESC);
-- first = 2,先多取一行判断 hasNextPage
SELECT id, created_at, title
FROM posts
ORDER BY created_at DESC, id DESC
LIMIT 3;
-- 第一页实际返回 4、3,所以下一页 after 对应 (10:00, 3)
SELECT id, created_at, title
FROM posts
WHERE (created_at, id) < (
TIMESTAMPTZ '2026-08-24 10:00:00+00',
3
)
ORDER BY created_at DESC, id DESC
LIMIT 3;预期输出:
SET
CREATE TABLE
INSERT 0 4
CREATE INDEX
-- 第一条 SELECT
id | created_at | title
----+------------------------+-------
4 | 2026-08-24 10:01:00+00| D
3 | 2026-08-24 10:00:00+00| C
2 | 2026-08-24 10:00:00+00| B
-- 第二条 SELECT
id | created_at | title
----+------------------------+-------
2 | 2026-08-24 10:00:00+00| B
1 | 2026-08-24 09:59:00+00| A实际 psql 的空格和时间显示格式可能不同,但行顺序应一致。第二条查询中的行值比较与排序方向保持一致:降序翻页使用“小于当前边界”。如果改成升序,就应相应改为“大于当前边界”。
让 GraphQL Connection 层只负责封装
数据层返回 first + 1 行后,GraphQL 层只保留前 first 行作为 edges。如果存在额外一行,则 pageInfo.hasNextPage 为 true;endCursor 由实际返回的最后一行排序键生成,而不是由那一行“额外记录”生成。这样 GraphQL 层不需要先拉取大量数据再在内存中分页。
例如第一页读取到 4、3、2 时,只返回 4、3,并以记录 3 的 (created_at, id) 生成 endCursor;记录 2 只用于证明还有下一页。下一次请求解码 Cursor 后,数据库从 (10:00, 3) 之后继续扫描,避免 OFFSET 随页数增大而重复跳过前面的行。
处理过滤、并发写入与空值
Keyset 条件必须和过滤条件一起设计索引。若查询固定包含 tenant_id、status,常见索引会把高选择性的等值过滤列放在排序键之前,例如 (tenant_id, status, created_at DESC, id DESC);是否有效仍应以真实 EXPLAIN (ANALYZE, BUFFERS) 验证,而不是只看索引是否存在。
并发插入通常不会让已经向后翻页的 Cursor 回到新插入的更前位置,这是 Keyset Pagination 的正常语义;如果业务要求跨多页看到完全一致的快照,就需要额外的一致性策略。排序列还应尽量 NOT NULL,因为 NULL 会让比较语义复杂化;若必须允许 NULL,应明确 NULLS FIRST/LAST 并设计对应游标编码与条件。
当排序字段可被更新时,记录可能跨越游标边界,导致重复或遗漏,因此优先选择创建时间、单调序列或其他分页期间稳定的键。只有“稳定排序键、同向范围条件、匹配索引、GraphQL 只封装结果”四件事同时成立,Cursor 分页才真正落到数据库而不是换一种形式的内存分页。