Cursor 分页快照一致性：查询身份、稳定成员集与过期合同

REST API 分页设计和数据库 Cursor 与 OFFSET已经解释 keyset 的性能与复合排序键，但 WHERE (created_at,id) < cursor 只固定上一页边界，不固定整个结果集。翻页期间一条旧记录若更新后越过边界，可能重复出现；反向移动则可能永远漏掉。删除、筛选字段变化和读副本延迟还会制造空页。生产 API 必须先回答“用户是在看实时窗口，还是遍历同一个快照”。

把一致性等级写进合同

LIVE_KEYSET 允许每页读取当下数据，只保证单次查询全序和边界正确，适合动态 feed；它必须公开说明跨页可能因更新而变化。导出、审计和批量处理使用 SNAPSHOT_TRAVERSAL：首请求固定成员语义，后续页必须来自同一 snapshot。不能用一个 cursor=true 参数暗示两种不同保证。

签名 page.cursor.v1 至少包含 tenant/principal scope、endpoint 与 API revision、规范化 filter digest、sort schema/direction、snapshot ID、边界完整元组、授权 epoch、page-size 上限、签发/到期时间和 signing key generation。客户端可以把 limit 调小，但不能改 filter、排序或扩大上限；任何不匹配返回稳定的 CURSOR_CONTRACT_MISMATCH。Base64 只是编码，必须用服务端签名防止构造跨租户边界。HTTP Link relation 可按 RFC 8288 暴露 next/prev，真正的状态仍在 opaque cursor 内。

排序必须形成全序，例如 (updated_at DESC, id DESC)，索引、NULL 顺序和数据库 collation 都绑定 sortSchema=v3。REST API 版本控制用于迁移新排序合同；旧 cursor 在其兼容 reader 和期限内继续解码，不能用新比较规则猜读。

快照实现取决于数据是否可变

仅追加且排序字段不可变的集合，可在首屏记录 highWatermark，之后同时限定 sequence <= watermark；这能排除新插入，删除是否可见仍需合同说明。对会更新排序或筛选字段的集合，高水位不够：需要双时态/versioned row 按 valid_from <= snapshot < valid_to 查询，或在首请求物化有序成员 ID 与版本摘要。读取每项时仍重验当前授权；快照一致性不能恢复已撤销的数据访问。

PostgreSQL REPEATABLE READ 能给一个事务一致快照，但把事务跨任意 HTTP 翻页长期保持会钉住 xmin、阻碍 vacuum，并把连接泄漏变成存储风险。短导出可以由服务端 job 在一个受限事务内持续读取；交互式分页应使用可回收的历史版本、物化成员清单或有 TTL 的搜索 snapshot 服务，而不是把数据库 snapshot ID 当永久 cursor。后台任务队列更适合长导出，客户端只轮询 job artifact。

snapshot registry 状态为 ISSUED -> ACTIVE -> COMPLETED | EXPIRED | REVOKED，记录成员/水位摘要、reader version、到期与最大页数。每个 cursor 带随机 transition ID；首次读取用 CAS 创建 PageRead(transitionId, boundaryDigest, resultDigest, nextCursorDigest) 并只增加一次页数，重复请求返回同一页与同一 next cursor，不再次消耗配额。同一 transition 若边界或请求摘要不同则冲突；是否允许从不同已签发 cursor 分叉读取也必须在合同中声明。过期返回 SNAPSHOT_EXPIRED 和重新开始入口，不能悄悄换成新快照继续。

删除、复制延迟和权限是独立轴

物化成员里的记录被业务删除时，审计型快照可返回版本化 tombstone；普通列表可跳过，但必须继续扫描直到填满页或到达终点，不能因过滤后数组不足就误判 hasMore=false。授权 epoch 提高时，旧 cursor 整体失效或逐项强制重验；任何方案都不允许返回已撤权正文。数据库读副本带来的 lag 也不能让页面跨不同水位，snapshot 必须路由到能证明已追上对应 revision 的副本，否则回主库或返回暂不可用。

故障套件在页边界制造相同时间戳、把记录从第三页更新到第一页、删除上一页最后一项、改变筛选字段、插入 watermark 之后的数据、切到落后副本、轮换签名 key、篡改 tenant/filter/limit、重复请求同一 cursor，并让 snapshot 在请求中途过期。对固定 fixture 完整遍历，成员 ID/版本 multiset 必须与首屏 snapshot oracle 完全相等；权限撤销项则只能减少且留下 reason，不得泄漏。

上线门要求 10 万轮随机并发变异中未解释的重复和漏项均为 0、跨租户或签名绕过为 0、快照过期误续为 0、P99 页查询满足接口 SLO、最长 snapshot 年龄和物化字节低于硬上限，且副本水位不足全部可观测。先为现有 cursor shadow 解码并比较，再让 5% 导出使用 snapshot v1。异常时停止签发新 snapshot、让已签发者在固定期限内由兼容 reader 排空；回滚入口不删除 registry，也不把旧 cursor 静默解释为 live 查询。

延伸阅读

• REST API 分页设计
• 数据库 Cursor 与 OFFSET
• 数据库读副本
• REST API 版本控制