工单列表已经加载两页,这时有人在顶部插入一条工单。用户继续翻页,上一页的最后一条又出现了。把重复项去掉后,页面看起来恢复正常,但删除、修改排序字段引起的漏项仍然存在。分页首先是对“下一页是什么”的约定,然后才是滚动组件的实现。
本文用一个按创建时间倒序排列的工单列表讨论接口和前端状态。例子是设计演练,不对应某个线上事故,也不把去重后的列表当成完整性证明。
页码描述位置,游标描述边界
假设每页两条,初始顺序为 A、B、C、D。读完 A、B 后插入 X,OFFSET 2 返回 B、C;如果反而删除 A,第二页可能从 D 开始,C 就被跳过。问题来自位置会移动。对一个持续变化的集合,“跳过前两条”并不是稳定边界。
游标可以携带上一页最后一项的排序键,但仅有 created_at 不够:同一毫秒创建的工单可能有多条。应使用 (created_at, id) 形成唯一顺序,并为查询设计相匹配的索引。可空排序字段还要规定空值放在哪一边,不能把 SQL 的未知比较结果留给前端猜测。
多取一条,用结果决定是否还有下一页
下面的查询省略了首屏分支;首屏不带游标条件。每页显示 20 条,查询 21 条,用额外一条判断是否存在后续记录。下一游标取实际返回给用户的第 20 条,不能取被截掉的第 21 条,否则会漏掉一条。行比较语义可参考 PostgreSQL 行比较,LIMIT/OFFSET 的行为见官方说明。
-- $1: tenant, $2: cursor created_at, $3: cursor id
SELECT id, created_at, title
FROM tickets
WHERE tenant_id = $1
AND (created_at, id) < ($2, $3)
ORDER BY created_at DESC, id DESC
LIMIT 21;
export function appendPage(current, incoming) {
const byId = new Map(current.map(row => [row.id, row]));
for (const row of incoming) byId.set(row.id, row);
return [...byId.values()];
}
去重函数只解决重叠响应。它保留已有项目的位置,并用新响应更新该项目的数据;如果标题变化还影响本地排序,就必须另外规定重排策略。不要一边宣称顺序由服务端保证,一边又在客户端按更新时间随意排序。
游标必须绑定查询身份
把状态筛选从“处理中”切到“全部”,旧游标就不再适用。接口可将租户、筛选摘要、排序版本和最后一个排序键绑定到一个不透明游标。Base64 只是编码,不能防篡改;需要完整性保护的场景应在服务端校验签名或查找服务端游标记录。每次请求仍然独立做权限检查。
前端用规范化后的筛选和排序生成 queryKey,切换时清空分页链,并给请求分配世代号。即使取消请求,旧响应仍有可能已经到达;落地结果前再核对世代号,才能避免把两个筛选结果拼在一起。缓存也按查询身份分区,不以页面序号作为唯一键。
稳定边界不等于同一份快照
当工单的排序字段不可变时,游标能避免顶部新增造成的位置漂移。但如果排序依据是可修改的优先级,一条工单可能越过边界,再次出现或永远落在已读区域。客户端按 ID 去重不能找回未收到的项目。业务必须决定这是实时列表还是固定导出。
实时列表可以接受局部变化,显示“有新内容”提示,并在用户主动刷新时重置边界。审计导出则需要服务端快照、物化结果或受控的一致性读取。单独加一个 asOf 时间过滤通常只能限制新增;若旧记录仍会修改或删除,它并没有冻结整个结果集。
把验收集中在边界移动上
至少复现五组序列:同一时间戳的多条记录、翻页间插入、翻页间删除、排序键修改,以及筛选切换后旧请求才完成。前端断言查询世代和展示 ID,接口测试断言顺序和下一游标,快照模式还应验证集合完整性。
分页错误最容易被“多滚几次好像正常”掩盖。把初始集合、每次变更和每次返回值写成固定样例,团队才能明确哪些变化允许用户看到,哪些变化必须触发刷新。
