好的实现不会依赖用户反复刷新碰运气，而会让每个阶段有明确输入、输出、超时和终态。 offset 在前面插入数据后会移动，导致重复或漏项。cursor 应编码最后一个排序元组，例如 (createdAt,id)，查询使用严格比较。
API 契约不仅是字段类型，还包括单位、缺省语义、幂等性、错误分类和版本窗口。客户端必须能区分可重试、需用户操作与永久拒绝，避免统一重试制造副作用。
先定义系统契约
这项能力横跨客户端、网络与服务端，局部最优很容易制造全局故障。工程决策需要同时约束两端行为、持久化事实和运维预算。
- 排序字段不可变并含唯一 ID，cursor 版本化、签名且绑定筛选；响应给 next/prev 和 hasMore，不允许客户端修改内部值。
- 所有输入都设置大小、次数和时间预算，并在超限时返回可操作的稳定错误码。
- 兼容性通过显式能力协商决定，旧客户端得到可解释的降级路径，而不是进入半可用状态。
“游标分页的稳定排序：新增和删除时不重复也不漏项”的交付标准是正常路径可用、异常路径收敛、资源有界，并且用户能理解系统为何采用当前状态。 这样得到的不是演示代码，而是能解释、能降级、能回滚的生产能力。
哪些情况会破坏契约
失败路径需要与成功路径共享同一套状态模型。只弹一个错误提示却不释放资源、不传播终态，下一次恢复就会继承脏状态。
- 只用秒级 createdAt 会在同秒记录间跳项；cursor 不绑定用户与过滤条件可被拿到其他数据集探测。
- 旧响应在新任务建立后迟到，如果没有版本隔离，会把健康状态覆盖成失败或再次启动已取消工作。
- 降级路径从未压测，主路径故障时所有流量同时进入更慢、更昂贵的后备方案。
如何逐条验证契约
测试不能以“最后成功了”结束。还要测量经历了多少次副作用、等待多久、是否泄露内容，以及失败后再次执行能否从干净基线开始。
- 分页过程中在头尾和当前边界插入、删除、修改记录，正反遍历必须无重复且符合文档化快照或实时语义。
- 让刷新、取消、超时和远端完成在同一调度窗口发生，断言系统只产生一个终态和一次副作用。
- 用故障注入验证告警先于用户投诉触发，并确认值班人员能从有限证据定位到具体阶段。
当实现能够安全降级、重复执行不产生额外副作用、故障指标早于投诉出现时，这项能力才算具备长期维护价值。