idempotency-design

Idempotency Design Skill — 幂等性设计

何时使用

• 设计写操作 API（创建订单 / 扣款 / 发短信 / 转账）
• 客户端 retry 但不知道服务端是否成功
• 消息队列消费者（at-least-once 投递）
• Webhook 接收方（请求方可能重发）
• 调试"用户被扣了两次款"

一、定义

幂等：执行 N 次（N≥1）的效果与执行 1 次相同。

不是"无副作用"，是"副作用合并"：

• DELETE /users/123 第一次删除，第二次返 404 / 204 但状态一致 → 幂等 ✅
• POST /payments 第一次扣 $10，第二次又扣 $10 → 不幂等 ❌

二、HTTP 方法幂等性（规范）

方法	幂等？	安全？
GET / HEAD	✅	✅（无副作用）
OPTIONS	✅	✅
PUT	✅（替换）	❌
DELETE	✅	❌
POST	❌（默认）	❌
PATCH	❌（默认）	❌

关键：HTTP 方法的幂等性是契约而不是自动保证。PUT /users/123 实现里如果每次 +1 计数器，就不幂等了——是实现错误。

三、为什么 exactly-once 是个神话

真相：在分布式系统中，at-most-once + at-least-once 才存在；exactly-once 是端到端业务层面的幻觉。

实现路径：

at-least-once 投递 + 消费端幂等 = 业务上的 exactly-once

关键设计原则：永远假设上游会重发，消费端必须幂等。

四、Idempotency Key 标准模式（Stripe 标杆）

客户端

POST /v1/charges
Idempotency-Key: 8e3a5f4c-2b3d-4f1e-9c8a-1d2e3f4a5b6c
Content-Type: application/json

{ "amount": 1000, "currency": "USD", "customer": "cus_xxx" }

客户端为每个唯一业务请求生成一个 key（UUID v4）。重试同一个请求复用同一个 key。

服务端逻辑

1. 收到请求，提取 Idempotency-Key
2. 查 idempotency 表 (key, request_hash, response, status, expires_at)
3. 找到 key:
   a. 状态 = COMPLETED → 直接返回缓存的响应
   b. 状态 = IN_PROGRESS → 返回 409 Conflict 或等待
   c. request_hash 不匹配 → 返回 422（同 key 不同 body 是错误）
4. 没找到 key:
   a. INSERT (key, request_hash, status=IN_PROGRESS) 用主键约束防并发
   b. 执行业务
   c. UPDATE 表 (response, status=COMPLETED)
   d. 返回响应
5. 失败时:
   a. 留 key 给客户端重试（24h TTL 后 GC）
   b. 或 DELETE key 让重试当新请求

数据库 schema

CREATE TABLE idempotency_records (
  key            TEXT PRIMARY KEY,
  user_id        BIGINT NOT NULL,             -- 配合 user 隔离
  request_method TEXT NOT NULL,
  request_path   TEXT NOT NULL,
  request_hash   TEXT NOT NULL,               -- SHA256(body) 防同 key 不同请求
  status         TEXT NOT NULL,               -- 'in_progress' | 'completed'
  response_code  INT,
  response_body  JSONB,
  created_at     TIMESTAMPTZ DEFAULT now(),
  expires_at     TIMESTAMPTZ NOT NULL          -- 24h 后清理
);

CREATE INDEX idx_idempotency_expires ON idempotency_records(expires_at);