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协议与服务端去重表约束，可在重试场景下保证一次性执行与结果可复用，提升一致性与用户体验。