什麼是 API 冪等性（Idempotency）？如何設計冪等 API？

API 冪等性（Idempotency）

定義

多次執行相同操作，結果與執行一次相同。

HTTP 方法的冪等性

方法	冪等	安全（無副作用）
GET	✅	✅
PUT	✅	❌
DELETE	✅	❌
POST	❌	❌
PATCH	❌（通常）	❌

為何重要？

• 網路不穩時，客戶端重試可能導致重複操作（如重複扣款）
• 冪等設計讓重試安全

實作方式：Idempotency Key

1. 客戶端生成唯一 key（如 UUID）
2. 在 Header 帶上：Idempotency-Key: <uuid>
3. 伺服器以此 key 為索引，儲存操作結果（Redis / DB）
4. 相同 key 的重複請求直接回傳快取結果

儲存策略

• Redis（TTL 24 小時）：儲存 key → response 映射
• 需注意原子性：使用 Redis SET NX（SET if Not eXists）防止競態條件