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

概述目标：在网络波动或客户端重试下保障操作只执行一次，通过幂等性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协议与服务端去重表约束，可在重试场景下保证一次性执行与结果可复用，提升一致性与用户体验。