Skip to content

游標分頁的一致性:新增、刪除和排序變化後,列表還可信嗎

工單列表已經載入兩頁,這時有人在頂部插入一條工單。使用者繼續翻頁,上一頁的最後一條又出現了。把重複項去掉後,頁面看起來恢復正常,但刪除、修改排序欄位引起的漏項仍然存在。分頁首先是對“下一頁是什麼”的約定,然後才是滾動組件的實現。

本文用一個按建立時間倒序排列的工單列表討論介面和前端狀態。例子是設計演練,不對應某個線上事故,也不把去重後的列表當成完整性證明。

頁碼描述位置,游標描述邊界 ​

假設每頁兩條,初始順序為 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 的行為見官方說明。

sql
-- $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;
javascript
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,介面測試斷言順序和下一游標,快照模式還應驗證集合完整性。

分頁錯誤最容易被“多滾幾次好像正常”掩蓋。把初始集合、每次變更和每次返回值寫成固定樣例,團隊才能明確哪些變化允許使用者看到,哪些變化必須觸發刷新。

MIT Licensed