API幂等性Key与去重最佳实践

---

title: API幂等性Key与去重最佳实践

keywords:

• 幂等性
• Idempotency-Key
• 去重
• 重试
• 一致性

description: 设计并实现API幂等性Key与服务端去重逻辑，提供可验证的请求头与数据库约束方案，保障重试安全与一致性。

date: 2025-11-26

tags:

• API
• Idempotency-Key
• 一致性
• 去重
• 幂等
• 幂等性
• 设计
• 重试

categories:

• 文章资讯
• 技术教程

---

概述

• 目标：在网络波动或客户端重试下保障操作只执行一次，通过幂等性Key实现服务端去重与结果复用。
• 适用：订单创建、支付扣款、资源创建等具副作用操作。

核心与实战

• 请求头约定：

Idempotency-Key: 7f6e9c2a-2f1b-4a9e-a2c0-8c5c9a

• 服务端去重逻辑：

-- 将Key与业务唯一参数组合（如user_id+payload_hash）写入幂等表
-- 若Key存在且状态成功，直接返回之前结果；若进行中，返回等待或队列化

• 数据库约束（PostgreSQL示例）：

CREATE TABLE idempotency (
  key text PRIMARY KEY,
  user_id bigint NOT NULL,
  payload_hash text NOT NULL,
  status text NOT NULL,
  response jsonb,
  created_at timestamp NOT NULL DEFAULT now()
);

CREATE UNIQUE INDEX idx_idem_user_payload ON idempotency(user_id, payload_hash);

• 处理流程（伪代码）：

BEGIN;
INSERT INTO idempotency(key, user_id, payload_hash, status)
VALUES ($key, $user, $hash, 'PROCESSING')
ON CONFLICT (key) DO NOTHING;

-- 如果插入成功则执行实际操作并更新记录
-- 如果冲突，则根据记录状态决定复用或等待

COMMIT;

示例

• 复用响应：

-- 当幂等表中存在成功记录时返回保存的response，避免再次执行副作用

• 过期与清理：

-- 设置保留期（如7天）定期清理历史Key

验证与监控

• 冲突与重复率：
• 监控幂等冲突次数与复用率；评估客户端重试质量。
• 正确性：
• 校验payload_hash一致性避免不同请求误复用；记录错误状态与失败原因。
• 安全性：
• Key应为不可预测值；避免业务敏感信息泄露在Key中。

常见误区

• 仅以Key做唯一约束忽视payload一致性；需结合用户与payload哈希。
• 将Key长期保留导致表膨胀；需定期清理与归档。
• 幂等与去重逻辑分散在多个服务造成不一致；应集中治理或共享库实现。

结语

• 通过明确的幂等性Key协议与服务端去重表约束，可在重试场景下保证一次性执行与结果可复用，提升一致性与用户体验。