API 幂等性设计实战 2026：让重试、双击与消息重复只生效一次

几乎每一个后端工程师都见过或写过这样的事故：用户网络卡顿连点两次"立即支付"，订单系统创建了两笔订单；调用方设置了超时重试，服务端其实已经处理成功，结果业务执行了两遍；消息队列重投递了一条消息，库存被扣了两次。**这些问题的共同点是：请求被重复发送了，而接口没有能力识别"这是同一件事"。**幂等性（Idempotency）就是给系统装上这种识别能力——同一个意图执行一次和执行多次，最终状态完全相同。它不是一个可以后期补上的中间件，而是从客户端发请求的那一刻就要开始设计的系统工程。

---

一、先看清"重复"从哪里来：四个真实来源

重复请求不是小概率事件，在现代系统架构里，它是内建的：

重复请求的四个来源：

① 用户行为
   双击提交按钮、网络转圈时刷新页面、
   App 退后台后重新进入自动重放。

② 客户端/网关重试
   HTTP 客户端超时重试、移动网络切换重连、
   负载均衡与服务网格的失败重试。

③ 消息队列的投递语义
   Kafka / RocketMQ / SQS 的常规保证是
   "至少一次"（at-least-once），
   消费者必须接受消息重复到达。

④ 第三方回调
   支付、物流、短信平台的回调可能
   以任意顺序、任意次数重试投递，直到收到成功响应。

关键认知转变：**不要试图消灭重复，那是做不到的；要让重复变得无害。**重试机制本身是可靠性的朋友（没有重试，一次网络抖动就是一次失败），幂等设计的目标是让"重试 + 幂等"在效果上等价于"精确一次"。

---

二、什么是幂等：从 HTTP 语义说起

幂等的数学定义很简单：对同一操作，执行一次与执行 N 次，系统的最终状态相同。

f(x)  = y
f(f(x)) = y
f(f(...f(x))) = y   ← 无论执行多少次，结果收敛到同一状态

对照 HTTP 方法，语义天然分层：

天然幂等的操作：
  GET    读取，不改变状态，天然幂等。
  PUT    用给定状态整体替换资源，重复替换结果相同。
  DELETE 删除一个资源，第一次删除后资源已不存在，
         后续删除返回 404，状态仍为"已删除"，语义幂等。

非幂等的操作：
  POST   "创建"语义，每次执行都可能产生一个新资源。
  PATCH  增量修改（如余额 +100），重复执行会累加，非幂等。

注意一个常见误区："接口幂等"不等于"接口返回相同"。重复的 DELETE 第二次返回 404，重复的支付第二次返回"订单已处理"，响应可以不同，但系统状态不能被二次改变。幂等约束的是副作用，不是响应报文。

业务操作的幂等性需要具体分析：

幂等的业务操作：
  "把订单状态设置为已支付"
    → 执行多少次都是"已支付"，状态机收敛。

非幂等的业务操作：
  "从账户余额扣减 100 元"
    → 执行两次扣 200，必须配业务唯一键保护。

看似幂等实则危险：
  "给账户加 100 积分"
    → 即使最终值覆盖写入，若读取-计算-写入分三步，
      并发下仍会丢更新。

---

三、幂等键：让客户端为"同一个意图"提供身份证

对于 POST 创建类操作，业界标准做法是客户端生成幂等键（Idempotency-Key），随请求一起发送：

POST /api/orders HTTP/1.1
Idempotency-Key: 7b2f9c1e-4a6d-4e8a-b3f2-8c91d5e7a0f3
Content-Type: application/json

{ "planId": "pro_monthly", "couponCode": "LAUNCH20" }

为什么键要由客户端生成，而不是服务端按参数哈希？因为只有客户端知道"两次点击是同一意图"还是"用户真的想下两单"：

场景对比：
  用户双击"提交订单"
    → 两次请求必须携带同一个幂等键（按钮生成一次，重试复用）
    → 服务端识别为重复，只创建一单。

  用户下单成功后，再买一份送朋友
    → 业务参数完全相同，但意图不同
    → 客户端必须生成新的幂等键，服务端创建第二单。

幂等键的工程要点：

① 全局唯一：优先使用 UUID，不要用自增序列（可猜测、易碰撞）。
② 一次意图一个：提交动作发生时生成，存在提交上下文里，
   该动作的所有重试复用同一键；新意图换新键。
③ 随重试传递：HTTP 客户端的重试逻辑必须原样带上该请求头。
④ 服务端绑定参数：幂等键要与请求体指纹绑定，
   防止同一个键被拿去提交不同内容。

前端在提交场景的典型实现：按钮点击时生成键并锁定，整个提交流程复用：

/**
 * 为一次提交意图生成并固定幂等键
 * 双击、超时重试都复用同一次点击产生的键
 */
function useSubmitOnce() {
  // 用 ref 保证同一次提交意图内键不变
  const keyRef = useRef<string | null>(null);

  /** 获取当前提交意图的幂等键（无则生成） */
  function getIdempotencyKey(): string {
    if (!keyRef.current) keyRef.current = crypto.randomUUID();
    return keyRef.current;
  }

  /** 提交完成（成功或彻底失败）后重置，允许下一次新意图 */
  function resetIntent() {
    keyRef.current = null;
  }

  return { getIdempotencyKey, resetIntent };
}

---

四、服务端去重：一张幂等表 + 一个状态机

服务端收到带幂等键的请求后，核心是维护一张去重记录表，并让"第一次请求"与"重复请求"走不同分支。

-- 幂等请求记录表：一个键一行，唯一约束兜底并发
CREATE TABLE idempotent_requests (
  id              BIGSERIAL PRIMARY KEY,
  idempotency_key TEXT        NOT NULL,
  request_fingerprint TEXT    NOT NULL,  -- 请求体指纹，校验同一键未被挪用
  status          TEXT        NOT NULL,  -- processing / succeeded / failed
  response_body   TEXT,                  -- 成功后缓存的响应，重复请求原样返回
  status_code     INT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
  completed_at    TIMESTAMPTZ,
  CONSTRAINT uq_idempotency_key UNIQUE (idempotency_key)
);

三态状态机是整个设计的灵魂，它处理的不是简单的"有/无"，而是请求正在处理中这个最棘手的窗口：

幂等记录状态机：

  （键不存在）
       │ 首次请求：INSERT ... processing（唯一约束保证只有一个成功）
       ▼
  processing（处理中）
       ├── 业务执行成功 → succeeded + 存响应
       ├── 业务执行失败 → failed（允许同键重试）
       └── 重复请求此时到达 → 返回 409 Conflict 或"处理中，请稍后查询"

  succeeded（已完成）
       └── 重复请求到达 → 不执行业务，直接回放缓存的响应

  failed（已失败）
       └── 同键重试到达 → 允许重新执行业务（回到 processing）

用 SQL 表达"抢占式插入"，让数据库唯一索引裁决并发：

-- 第一个请求插入成功；并发的重复请求因唯一约束失败
INSERT INTO idempotent_requests (idempotency_key, request_fingerprint, status)
VALUES ($1, $2, 'processing')
ON CONFLICT (idempotency_key) DO NOTHING;
-- 影响行数为 1：抢占成功，由我执行业务
-- 影响行数为 0：键已存在，走重复/处理中分支

服务端的完整编排（与业务操作在同一事务边界内完成状态落库）：

/**
 * 幂等执行器：抢占键 → 校验指纹 → 执行业务 → 记录结果
 * 重复请求不会进入业务函数
 */
async function executeIdempotently<T>(input: {
  key: string;
  payload: unknown;
  execute: () => Promise<{ status: number; body: T }>;
}): Promise<{ status: number; body: T; replayed: boolean }> {
  const fingerprint = hashPayload(input.payload);

  // 第一步：尝试抢占幂等键
  const acquired = await tryInsertProcessing(input.key, fingerprint);

  if (!acquired) {
    // 键已存在：读取既有记录决定如何响应
    const existing = await getRequestRecord(input.key);

    if (existing.request_fingerprint !== fingerprint) {
      // 同一幂等键携带了不同请求体：明确拒绝，这是客户端 bug 或攻击
      return { status: 422, body: { error: "idempotency_key_reused" }, replayed: false };
    }

    switch (existing.status) {
      case "succeeded":
        // 已完成：回放首次的响应，副作用绝不重复执行
        return { status: existing.status_code, body: JSON.parse(existing.response_body), replayed: true };
      case "processing":
        // 首个请求仍在执行：让调用方稍后重试/查询，不要并发执行业务
        return { status: 409, body: { error: "request_in_progress" }, replayed: false };
      case "failed":
        // 上次失败：允许同键重新尝试（递归重新抢占由上层保证）
        return retryFailedRequest(input);
    }
  }

  // 第二步：抢占成功，执行业务（仅此一次）
  try {
    const result = await input.execute();
    await markSucceeded(input.key, result.status, JSON.stringify(result.body));
    return { ...result, replayed: false };
  } catch (err) {
    await markFailed(input.key);
    throw err;
  }
}

两个实现细节决定可靠性：

细节一：状态写入与业务操作的事务边界
  最佳实践是业务提交与幂等记录置为 succeeded 在同一数据库事务中，
  避免"业务成功了但记录还停在 processing"的悬挂状态。
  跨系统无法同事务时（如还要调外部接口），用 processing +
  对账补偿兜底（见第八节）。

细节二：processing 必须有租约超时
  进程可能在处理中途崩溃，记录永远停在 processing。
  给记录加过期时间（如几分钟），超时后允许同键安全重试，
  前提是业务操作本身具备可重入性。

---

五、为什么不能只靠"先查后插"：并发竞态

很多人第一版的幂等写法是"先 SELECT 查键是否存在，不存在再 INSERT 并执行业务"。在低并发下它看起来工作正常，但两个并发请求会同时通过检查：

危险的检查时序（检查与执行不是原子操作）：

  请求 A：SELECT → 不存在 ──────────► 执行业务（下单）
  请求 B：────── SELECT → 不存在 ──► 执行业务（重复下单！）

正确的裁决者只有一个：数据库的唯一约束（或等价的原子原语）。INSERT 的唯一索引冲突是数据库内核保证的原子事实，不存在"同时插入成功"的间隙。

-- 业务表自身也要有唯一约束，幂等表之外再加一道保险
-- 例如支付流水：同一业务订单只允许一条成功支付流水
CREATE UNIQUE INDEX uq_payment_success
  ON payments (order_id)
  WHERE status = 'succeeded';

纵深防御的原则是：**幂等键表挡在接口层，业务唯一约束挡在数据层。**即使幂等逻辑有 bug，数据库约束也能阻止第二条"同一订单的成功支付"落库。应用层做友好提示，数据库做最终裁决。

关于分布式锁：
  可以用 Redis SET NX 等锁串行化同键请求，但要注意——
  锁只是"减少并发"，不是"证明唯一"：锁过期、主从切换、
  客户端超时都可能让锁失效。
  结论：锁可以用于削峰与互斥，但最终的唯一性
  必须由数据库约束背书，不要只靠锁做幂等。

---

六、响应复用：让重试者拿到与首次一致的结果

幂等不只是"别重复执行"，还包括让调用方拿到确定的结果。考虑支付场景：第一次请求已经扣款成功，但响应在网络中丢失，客户端重试——如果服务端只返回"请求处理中"，客户端无法确认是否扣款，用户体验和对账都会出问题。

因此首次成功的响应应当被持久化，重试时原样回放：

/**
 * 首次成功后保存可回放的响应
 * 响应体、状态码、资源定位一并落库
 */
async function markSucceeded(key: string, status: number, body: string) {
  await db.query(
    `UPDATE idempotent_requests
       SET status = 'succeeded',
           status_code = $2,
           response_body = $3,
           completed_at = now()
     WHERE idempotency_key = $1`,
    [key, status, body],
  );
}

响应复用时的语义约定：

① 回放的是"首次成功响应"：包括资源 id、状态、跳转地址，
  调用方据此继续流程，结果与请求只发一次完全一致。
② 不重新计算易变字段：不要在回放时重新生成时间戳、
  重新取号，否则两次响应不一致会让调用方误判。
③ GET 兜底查询：对于无法回放的场景，提供按幂等键
  查询状态的接口，让客户端轮询确认最终结果。

---

七、重试与超时：和幂等配套的另一半设计

幂等键让重试变得安全，但"安全地重试"还需要正确的重试策略，否则会制造无意义的洪峰与更难排查的竞态：

错误分类决定"能不能重试"：

可重试错误（瞬时故障）：
  连接超时、502/503/504、429（被限流）、DNS 抖动。

不可重试错误（确定失败）：
  400 参数错误、401/403 鉴权失败、404、422 语义错误。
  重试一万次结果也一样，只会浪费资源。

重试必须配指数退避与抖动（jitter），避免故障恢复时所有客户端同时重放形成"惊群"：

/**
 * 计算带抖动的指数退避延迟
 * 退避翻倍 + 随机抖动，打散重试洪峰
 */
function backoffDelay(attempt: number, baseMs = 200, maxMs = 8000): number {
  const exp = Math.min(baseMs * 2 ** attempt, maxMs);
  return Math.random() * exp; // 0 ~ exp 之间的随机抖动
}

/**
 * 仅对可重试状态码发起重试，每次重试复用同一幂等键
 */
async function callWithRetry<T>(fn: (key: string) => Promise<T>, key: string): Promise<T> {
  let attempt = 0;
  for (;;) {
    try {
      return await fn(key); // 关键：重试时原样传入同一幂等键
    } catch (err) {
      if (!isRetryable(err) || attempt >= MAX_ATTEMPTS) throw err;
      await sleep(backoffDelay(attempt));
      attempt += 1;
    }
  }
}

/** 判断 HTTP 错误是否属于值得重试的瞬时故障 */
function isRetryable(err: unknown): boolean {
  const status = (err as { status?: number }).status;
  return status === 429 || status === 502 || status === 503 || status === 504;
}

超时设置要与服务端处理时长匹配：超时时间应略大于服务端 P99 处理时间，否则"客户端已超时、服务端还在执行"会制造大量真实的重复——幂等能兜住结果，但无谓的重复执行仍在烧资源。

---

八、支付与第三方回调：幂等要求最高的战场

支付回调是幂等设计的教科书场景：平台会在收不到成功响应时反复重试，回调可能乱序，金额与状态必须绝对可靠。

支付回调处理的幂等要点：

① 回调入口只做两件事：验签 + 落待处理记录，尽快返回 200，
   耗时业务异步处理，避免平台因超时反复重推。
② 以平台流水号去重：第三方交易号具有全局唯一性，
   在回调记录表上建唯一索引。
③ 业务状态机只允许向前流转：
   待支付 → 已支付 → 已完成；
   "已支付"状态再次收到"已支付"回调，直接幂等返回成功。
④ 严禁用回调金额直接累加余额：
   必须是"订单状态置为已支付 + 按订单号发一次权益"，
   而非"收到回调就加钱"。

回调去重的核心 SQL：

-- 回调流水表：平台流水号唯一，重复回调插入即冲突
CREATE TABLE payment_callbacks (
  provider_tx_no TEXT PRIMARY KEY,   -- 第三方交易流水号
  order_id       TEXT NOT NULL,
  payload        JSONB NOT NULL,
  processed      BOOLEAN NOT NULL DEFAULT false,
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- 重复回调：INSERT 冲突即说明此前已收到，直接返回成功应答
INSERT INTO payment_callbacks (provider_tx_no, order_id, payload)
VALUES ($1, $2, $3)
ON CONFLICT (provider_tx_no) DO NOTHING;

即使所有防线都失效，还要有最后一道安全网——对账（reconciliation）：定期拉取第三方的交易流水，与本地订单逐笔比对，发现"平台已扣、本地未发货"或"本地重复"的差异并自动补偿或告警。幂等机制把事故概率压到极低，对账机制保证极端情况下错误一定能被发现和修复。

---

九、消息队列消费：在"至少一次"世界里实现精确一次的效果

主流消息队列提供的是至少一次投递：消费者处理完消息但在提交位点前崩溃，消息会被重新投递给另一个消费者实例。因此消费者必须幂等。

/**
 * 幂等的消息消费者：以业务唯一键去重，而非消息偏移量
 * 偏移量在重平衡/换分区时不可靠，业务键才是稳定身份
 */
async function consumeOrderEvent(event: OrderEvent): Promise<void> {
  // 以业务事件 id 抢占处理权（唯一约束裁决）
  const inserted = await db.one(
    `INSERT INTO consumed_events (event_id, consumer)
     VALUES ($1, $2)
     ON CONFLICT (event_id) DO NOTHING
     RETURNING event_id`,
    [event.eventId, CONSUMER_NAME],
  ).catch(() => null); // 冲突时返回 null

  if (!inserted) {
    // 该事件已被处理过：直接确认，不重复执行业务
    return;
  }

  await handleOrderEvent(event); // 真正的业务副作用只执行一次
}

与消息配合最常见的架构模式是 Outbox（发件箱模式），它用一张本地表同时解决"业务落库与发消息的原子性"，从源头减少不一致：

Outbox 模式工作流：

  业务事务 {
    1. 写入业务数据（如订单状态变更）
    2. 同事务写入 outbox 表（待发消息）
  }  ← 要么都成功，要么都失败，不存在"改了库没发消息"

  独立的投递进程 {
    轮询/CDC 读取 outbox → 投递到 MQ → 标记已投递
    （投递本身至少一次，消费端幂等去重，闭环安全）
  }

-- 发件箱表：与业务写入在同一事务内提交
CREATE TABLE outbox_events (
  id           BIGSERIAL PRIMARY KEY,
  aggregate_id TEXT NOT NULL,    -- 关联的业务实体
  event_type   TEXT NOT NULL,
  payload      JSONB NOT NULL,
  published    BOOLEAN NOT NULL DEFAULT false,
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

这条链路的可靠性组合可以总结为一句话：生产端用本地事务 + Outbox 保证不丢，投递端接受至少一次，消费端用业务唯一键幂等去重——三者拼起来，就是工程意义上的"精确一次效果"。

---

十、独立开发者的最小可用方案

幂等听起来重，但小团队和独立开发者不需要一上来就实现全套。按业务风险分层落地：

第一层（任何写接口都该做，成本极低）
  □ 提交按钮防重入（前端锁 + 提交期间禁用）
  □ POST 创建接口支持客户端幂等键
  □ 关键业务表加业务唯一约束（订单号、流水号）

第二层（涉及钱、库存、限量资源时必须做）
  □ 幂等记录表 + processing/succeeded/failed 状态机
  □ 成功响应回放
  □ 回调流水唯一去重 + 状态机单向流转

第三层（规模与可靠性要求提高时补齐）
  □ processing 租约超时与崩溃恢复
  □ MQ 消费幂等表 + Outbox 模式
  □ 与第三方的定时对账兜底

一个务实判断：**只要副作用涉及金钱、库存、限量名额或对外通知（短信、邮件、推送），幂等就不是可选项。**重复发一条欢迎邮件用户可以原谅，重复扣款一次用户可能永远离开。

---

结语：在不可靠的网络上构建确定的业务

分布式系统有一个无法回避的前提：网络会超时、进程会崩溃、消息会重复、节点会重启。在这样的地基上构建"只发生一次"的业务承诺，靠的不是祈祷这些故障不要发生，而是承认它们必然发生，然后用幂等键、唯一约束、状态机与对账把故障的后果一一消解。

好的幂等设计最终是隐形的：用户疯狂双击也只下一单，客户端大胆重试也不担心重复扣款，消息重复投递也只是一次无害的空操作。可靠性不是某段代码的属性，而是整条链路共同给出的承诺——而幂等，是这个承诺里最不能缺席的那块基石。