科普 · 工程

什麼是冪等鍵:以及您的應用程式為什麼需要一個

2026年11月4日 · Software by Design

每個能離線工作的應用程式,遲早都要回答同一個問題:使用者連按兩下「送出」,或者網路在請求中途斷掉、用戶端重送時,會發生什麼? 答案是一個叫冪等鍵的小機制:這裡講它怎麼運作,以及它在我們自己的程式碼裡長什麼樣。

一句話說清問題

網路不可靠,所以用戶端必須重試;重試意味著同一個邏輯動作會抵達不止一次;沒有保護,「不止一次」就是兩筆工時記錄、兩張發票、兩筆預訂。

注意問題不是什麼:不是「使用者點了兩下」。使用者確實會點兩下,但更常見的情形遠不那麼顯眼:工地上的行動應用失去訊號,把上班打卡排進佇列,伺服器套用了它,回應死在半路上,應用程式(正確地)又送了一遍。這筆重複,是系統在按設計工作。

機制

冪等鍵是用戶端按邏輯動作產生的唯一識別碼:不是按 HTTP 請求。用戶端把同一個鍵附在原始請求和該動作的每一次重送。伺服器記錄它見過的鍵;當一個鍵第二次抵達,伺服器回傳第一次的結果,而不是把變更執行兩遍。

三個特性讓它成立:

  • 鍵歸用戶端所有。如果由伺服器發放,用戶端在收到它之前的重送就無法被識別。鍵在裝置上鑄出:在我們的行動應用裡,是使用者打卡那一刻建立的 UUID,而不是發起網路呼叫的時候。
  • 記錄是認領,不是結果。伺服器先寫認領(「這個鍵歸我了,結果待定」),再做變更。並行的重送撞上這條認領,會等待或重送第一次的結果:它絕不可能在底下塞進第二次變更。
  • 認領綁定承載。我們把動作及其正規化輸入的雜湊和鍵一起存。同一個鍵配上不同的承載 → 409 衝突,而不是靜默覆蓋。重送永遠只該意味著「同一件事再來一次」。

它出現在我們應用程式的哪裡

ArbeitszeitCheck 的行動打卡佇列在每次重送中都帶著一個 clientRequestId;TourCheck 把同一份契約綁在檢查點確認裡的 client_event_id 上:一次重送會把整條認領(備註、照片、時間戳)與已存的列做比較。過期時間和去重一樣重要:我們的認領列存活七天:夠長,蓋得住一個長週末的訊號死角,又夠短,讓這張表一直是佇列而不是日誌。

給您自己應用程式的短版本

如果您的 API 會改變狀態、用戶端又能重送:而每個用戶端都能重送:您需要的恰好是三樣東西:每個動作一個用戶端產生的鍵、一列先寫的認領記錄、一個讓「同一個鍵」也意味著「同一個意圖」的承載雜湊。這就是整個模式。其餘一切:重送時間窗、清理工作、衝突狀態碼:都只是圍著這三條承諾的水電配管。