生产环境幂等必须客户端生成UUIDv4的Idempotency-Key并透传，服务端用Lua脚本原子校验Redis状态，数据库加唯一索引兜底，且需缓存完整响应三元组防悬挂与快照回传。
直接加数据库唯一约束或用 ConcurrentDictionary 做内存去重，在生产环境基本等于没做幂等——多实例部署下必然失效，网络重试+服务重启后照样重复落库。
Idempotency-Key 必须由客户端生成且不可推导
服务端不能自动生成或拼接 Idempotency-Key（比如用时间戳+IP+路径），否则前端重试时无法复用同一 key。真实场景中，用户点击“提交订单”后因超时重试，两次请求必须携带完全相同的 key，服务端才能识别为同一操作。
- 客户端应使用 UUID v4 生成 key，并通过 HTTP Header 传递：
Idempotency-Key: 7f8c4a2e-1b3d-4e5f-8a9c-0e1d2f3a4b5c - 服务端只校验格式（是否为合法 UUID）和长度（64 字符内），不解析、不修改、不补全
- 若 header 缺失或格式非法，直接返回
400 Bad Request，不进入业务逻辑 - 避免在日志中明文打印该 key（防止敏感链路泄露），可用哈希脱敏后记录
Redis 层必须用 Lua 脚本做原子预检
仅调 SETNX + EXPIRE 是错的——两步之间存在竞态窗口，两个并发请求可能同时判断“key 不存在”，然后都写入 processing，导致业务逻辑被执行两次。
- 必须用一段 Lua 脚本一次性完成：检查是否存在 → 不存在则设
"processing"并带过期 → 返回明确状态码 - 推荐脚本返回值语义：
1= 首次进入可执行；0= 已有终态结果（成功/失败）；2= 正在处理中（建议返回409 Conflict） -
ARGV[1]过期时间建议设为86400（24 小时），覆盖最长业务链路（如跨系统回调）+ 人工重试窗口 - 不要用
IDistributedCache.SetStringAsync简单封装，它底层仍是分步操作，无法保证原子性
数据库唯一约束是最后一道不可绕过的防线
Redis 可能宕机、被清空、或因网络分区不可达，此时所有请求都会穿透到 DB 层——如果没有兜底约束，重复数据就直接入库了。
- 在业务表（如
Orders）中新增非空字段：idempotency_key NVARCHAR(64) NOT NULL - 建唯一索引：
CREATE UNIQUE INDEX IX_Orders_IdempotencyKey ON Orders(idempotency_key) - 插入时不要先
SELECT再INSERT（查-插之间有竞态），而是直接INSERT ... ON CONFLICT DO NOTHING（PostgreSQL）或MERGE（SQL Server） - 更新操作必须配合状态机与乐观锁：
UPDATE Orders SET Status = 'Paid' WHERE Id = @id AND Status = 'Created' AND Version = @expectedVersion，并严格检查RowsAffected == 1
别忽略悬挂事务与响应快照回传
当接口涉及多个下游服务（如订单→库存→支付），即使每层都幂等，仍可能出现“前两步成功、第三步超时、上游重试导致第三步重复执行”的悬挂问题；同时，若 Redis 中缓存的是终态响应，但客户端重试时需要原样返回上次的 201 Created + Location 头，就不能只存状态。
- 必须在 Redis 中缓存完整响应三元组：
(StatusCode, BodyBytes, Headers)，而非仅字符串 "success" - 对长时间运行的操作（>5s），建议引入事务状态表（
IdempotencyRecords），记录key、Status（Pending/Success/Failure）、CreatedAt、UpdatedAt、RetryCount - 状态表本身也要加唯一索引，并在插入前用
MERGE或INSERT ... ON CONFLICT防止并发插入 - 若业务允许，对
2（processing）状态可选择阻塞等待（轮询 Redis 直到终态）或立即返回409，后者更利于前端控制重试节奏
最易被忽略的点是：Redis 的 key 过期时间与业务最大耗时不匹配——设太短，正常重试会失败；设太长，异常中断后 key 长期卡在 processing 状态，后续请求全被拒。这个阈值必须结合链路监控数据动态调整，不能拍脑袋定。
