工單列表已經加載兩頁,這時有人在頂部插入一條工單。用戶繼續翻頁,上一頁的最後一條又出現了。把重複項去掉後,頁面看起來恢復正常,但刪除、修改排序字段引起的漏項仍然存在。分頁首先是對“下一頁是什麼”的約定,然後才是滾動組件的實現。
本文用一個按創建時間倒序排列的工單列表討論接口和前端狀態。例子是設計演練,不對應某個線上事故,也不把去重後的列表當成完整性證明。
頁碼描述位置,游標描述邊界
假設每頁兩條,初始順序為 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,接口測試斷言順序和下一游標,快照模式還應驗證集合完整性。
分頁錯誤最容易被“多滾幾次好像正常”掩蓋。把初始集合、每次變更和每次返回值寫成固定樣例,團隊才能明確哪些變化允許用戶看到,哪些變化必須觸發刷新。
