ALL NOTES

LAB NOTES / 2026.11.03

冪等性 (Idempotent)|什麼是冪等性 (Idempotent)?如何防止重複扣款?

什麼是冪等性 (Idempotent)?

「冪等」這個詞源自數學。在計算機科學與網路通訊中,它的定義是:
無論向伺服器發送「同一個請求」一次,還是發送無數次,對伺服器產生的「副作用(Side Effect)」與最終狀態都是完全相同的。

可以想像成大樓的自動門按鈕,你按一下(發送 1 次請求)門會打開;如果你連續按十下(發送 10 次請求),門依然是打開的狀態,不會變成打開十次或壞掉。

為什麼冪等性在實務中很重要?

冪等性主要用來解決以下兩個常見痛點:

1. 網路逾時與自動重試:
當前端向伺服器發送一筆交易請求,卻因為網路不穩遲遲沒收到回應,客戶端(或 API Gateway)通常會自動重試。如果該操作是冪等的,重試就非常安全;如果不具備冪等性,重試可能會導致「重複扣款」或「重複建立訂單」。

2. 使用者防呆機制:
假設使用者在送出表單或點擊結帳按鈕時不小心連續點擊了兩次。如果後端沒有做好冪等控制,就會在資料庫寫入兩筆相同的資料。

如何讓非冪等的 POST 具備冪等性?

因為 POST 不具備冪等性(最常應用在建立訂單或付款),但在金流或電商系統中,我們絕不能容許因為網路重試而重複扣款。這時業界標準的做法是引入 Idempotency Key(冪等鍵):

  1. 前端生成唯一識別碼:前端在發送付款請求時,在 Request Header 夾帶一組唯一的 UUID(例如 Idempotency-Key: 9b1deb4d-3b7d-4bad-9bdd)。

  2. 後端快取與檢查:

    • 伺服器收到請求後,先檢查資料庫或快取裡有沒有處理過這個 Idempotency-Key。

    • 如果沒處理過:正常執行扣款/建單,並把「結果」存入快取中。

    • 如果已經處理過(遇到網路重試又傳了一次相同的 Key):直接回傳上一次快取的執行結果,絕對不重複執行業務邏輯。

掌握了冪等性,就能在設計和串接 API 時,預判網路異常情境並寫出更安全的前後端系統。

所有筆記