<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>Idempotency-Key on Bill.Lin&#39;s Notes</title>
		<link>https://xinqilin.github.io/tags/idempotency-key/</link>
		<description>Recent content in Idempotency-Key on Bill.Lin&#39;s Notes</description>
		<generator>Hugo</generator>
		<language>zh-tw</language>
		
		
		
		
			<lastBuildDate>Sun, 22 Nov 2026 00:00:00 +0800</lastBuildDate>
		
			<atom:link href="https://xinqilin.github.io/tags/idempotency-key/index.xml" rel="self" type="application/rss+xml" />
			<item>
				<title>冪等性與 Idempotency Key：讓重試變得安全</title>
				<link>https://xinqilin.github.io/post/systemdesign/idempotency-key/</link>
				<pubDate>Sun, 22 Nov 2026 00:00:00 +0800</pubDate>
				<guid>https://xinqilin.github.io/post/systemdesign/idempotency-key/</guid>
				<description>&lt;blockquote&gt;&#xA;&lt;p&gt;&lt;strong&gt;System Design 系列&lt;/strong&gt; Part 5-4｜上一篇：&lt;a href=&#34;https://xinqilin.github.io/post/systemdesign/pubsub-delivery-semantics/&#34;&gt;Pub/Sub 與投遞語意&lt;/a&gt;｜下一篇：&lt;a href=&#34;https://xinqilin.github.io/post/systemdesign/realtime-updates/&#34;&gt;即時更新&lt;/a&gt;｜&lt;a href=&#34;https://xinqilin.github.io/post/systemdesign/system-design-thinking/#%E7%B3%BB%E5%88%97%E5%9C%B0%E5%9C%96&#34;&gt;系列地圖&lt;/a&gt;&lt;/p&gt;&#xA;&lt;/blockquote&gt;&#xA;&lt;h2 id=&#34;情境與問題&#34;&gt;情境與問題&lt;/h2&gt;&#xA;&lt;p&gt;使用者在捷運上按下「報名並付款」。請求送到伺服器，報名成功、款項扣了，但回應在回程的網路上遺失了。App 等了 10 秒沒有回應，顯示「網路錯誤，請重試」。使用者再按一次。&lt;/p&gt;&#xA;&lt;p&gt;伺服器收到的第二個請求和第一個一模一樣。如果它照常處理，使用者就&lt;strong&gt;被扣了兩次錢&lt;/strong&gt;。&lt;/p&gt;&#xA;&lt;p&gt;這不是罕見的情況。網路逾時之後，用戶端&lt;strong&gt;無法分辨&lt;/strong&gt;請求是「沒送到」、「送到了但處理失敗」，還是「處理成功但回應遺失」。重試在每一層都會發生：&lt;/p&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;使用者重按按鈕&lt;/li&gt;&#xA;&lt;li&gt;App 或前端的 HTTP 用戶端自動重試&lt;/li&gt;&#xA;&lt;li&gt;API gateway、service mesh 的重試設定&lt;/li&gt;&#xA;&lt;li&gt;服務之間呼叫的重試（&lt;a href=&#34;https://xinqilin.github.io/post/systemdesign/timeout-retry-backoff/&#34;&gt;Part 6 的 Timeout 與 Retry&lt;/a&gt;）&lt;/li&gt;&#xA;&lt;li&gt;Message queue 的重新投遞（&lt;a href=&#34;https://xinqilin.github.io/post/systemdesign/message-queue/&#34;&gt;Message Queue 篇&lt;/a&gt;）&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;p&gt;前一篇已經說明，訊息系統的「exactly-once」實際上是「at-least-once + 冪等處理」。API 也一樣：&lt;strong&gt;要讓重試安全，操作本身必須是冪等的&lt;/strong&gt;。&lt;/p&gt;&#xA;&lt;h2 id=&#34;最簡單的做法與它的極限&#34;&gt;最簡單的做法與它的極限&lt;/h2&gt;&#xA;&lt;ul&gt;&#xA;&lt;li&gt;&lt;strong&gt;前端在送出後停用按鈕&lt;/strong&gt;：擋得住連點，擋不住逾時後的重試、App 被關掉重開、網路層的自動重試&lt;/li&gt;&#xA;&lt;li&gt;&lt;strong&gt;資料庫唯一鍵&lt;/strong&gt;：在 &lt;code&gt;(lecture_id, member_id)&lt;/code&gt; 加上唯一索引，同一個會員不能報名同一場講座兩次。這在報名上很有效，但有兩個限制：&#xA;&lt;ul&gt;&#xA;&lt;li&gt;重試的請求會收到「已經報名過」的錯誤，而第一次其實成功了。用戶端要特別處理這個錯誤，才知道「其實是成功的」&lt;/li&gt;&#xA;&lt;li&gt;不是每個操作都有天然的唯一鍵。加購講義可以買兩份、儲值可以儲兩次，「內容相同」不代表「是同一個操作」&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;/li&gt;&#xA;&lt;/ul&gt;&#xA;&lt;h2 id=&#34;核心機制&#34;&gt;核心機制&lt;/h2&gt;&#xA;&lt;h3 id=&#34;什麼是冪等&#34;&gt;什麼是冪等&lt;/h3&gt;&#xA;&lt;p&gt;一個操作執行一次和執行多次，對系統狀態的&lt;strong&gt;效果相同&lt;/strong&gt;，就是冪等的。注意是效果，不是回應：第二次刪除同一筆資料可能回 404，但資料的狀態沒有差別。&lt;/p&gt;&#xA;&lt;p&gt;HTTP 規格定義了方法的語意：GET、HEAD、PUT、DELETE 是冪等的，POST 不是，PATCH 不一定（&lt;a href=&#34;https://xinqilin.github.io/post/systemdesign/rest-grpc-graphql/&#34;&gt;REST、gRPC 與 GraphQL 篇&lt;/a&gt;）。這是語意上的承諾，實作也要遵守：一個會「每呼叫一次就加 1」的 PUT，違反了規格。&lt;/p&gt;&#xA;&lt;h3 id=&#34;讓操作天生冪等&#34;&gt;讓操作天生冪等&lt;/h3&gt;&#xA;&lt;p&gt;在加上 Idempotency Key 之前，先看操作本身能不能設計成冪等的：&lt;/p&gt;&#xA;&lt;table&gt;&#xA;&#x9;&lt;thead&gt;&#xA;&#x9;&#x9;&#x9;&lt;tr&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;th&gt;做法&lt;/th&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;th&gt;例子&lt;/th&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;th&gt;冪等嗎&lt;/th&gt;&#xA;&#x9;&#x9;&#x9;&lt;/tr&gt;&#xA;&#x9;&lt;/thead&gt;&#xA;&#x9;&lt;tbody&gt;&#xA;&#x9;&#x9;&#x9;&lt;tr&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;設定為某個值&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;&lt;code&gt;UPDATE registration SET status = &#39;CANCELLED&#39;&lt;/code&gt;&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;是&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&lt;/tr&gt;&#xA;&#x9;&#x9;&#x9;&lt;tr&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;增減某個值&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;&lt;code&gt;UPDATE lecture SET remaining = remaining - 1&lt;/code&gt;&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;否&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&lt;/tr&gt;&#xA;&#x9;&#x9;&#x9;&lt;tr&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;帶上預期版本的條件式更新&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;&lt;code&gt;... SET status = &#39;PAID&#39;, version = 8 WHERE id = ? AND version = 7&lt;/code&gt;&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;是，重試時版本已經不符，不會再更新一次&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&lt;/tr&gt;&#xA;&#x9;&#x9;&#x9;&lt;tr&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;用戶端決定資源的 ID&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;&lt;code&gt;PUT /v1/registrations/{用戶端產生的 UUID}&lt;/code&gt;&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;是，第二次只是覆寫同一筆&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&lt;/tr&gt;&#xA;&#x9;&#x9;&#x9;&lt;tr&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;天然的唯一鍵&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;&lt;code&gt;(lecture_id, member_id)&lt;/code&gt; 唯一索引&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&#x9;&#x9;&lt;td&gt;重複的寫入會被擋下&lt;/td&gt;&#xA;&#x9;&#x9;&#x9;&lt;/tr&gt;&#xA;&#x9;&lt;/tbody&gt;&#xA;&lt;/table&gt;&#xA;&lt;p&gt;能這樣設計就不需要額外的機制。但「建立一筆付款」「加購一份講義」這類操作，天生就不是冪等的，這時要用 Idempotency Key。&lt;/p&gt;</description>
			</item>
	</channel>
</rss>
