真正能落地的幂等方案必须满足：客户端提供稳定Idempotency-Key、服务端用Redis原子预检、数据库加唯一约束兜底；ConcurrentDictionary和lock因仅限单机而多实例下必然失效。
后端接口不做幂等控制，用户连点两次按钮、网络超时重试、前端防抖失效——都会生成重复订单、重复扣款、重复发券。这不是“概率低”，而是“必然发生”。真正能落地的幂等方案，必须满足三个硬条件：客户端提供稳定 Idempotency-Key、服务端用 Redis 做原子状态预检、数据库层加唯一约束兜底。单靠 ConcurrentDictionary 或 lock 在多实例下完全无效。
为什么 ConcurrencyDictionary 和 lock 在生产环境会失效
本地缓存类如 ConcurrentDictionary 或方法级 lock 只在单进程内有效。一旦部署到多个 IIS 实例、K8s Pod 或负载均衡后端，两个相同 Idempotency-Key 的请求可能被分发到不同机器，各自走通逻辑，最终写入两条重复记录。
- 客户端重试时，第一次请求已落库但响应丢失，第二次进来查不到任何状态（因缓存不共享），照样执行
-
lock锁的是当前线程或对象，对跨进程/跨机器无感知 - 即便用
IDistributedCache，若没配合 Lua 脚本做原子读-写-过期，仍可能在「查无记录 → 写 processing」之间被另一个请求插入终态结果，造成状态覆盖
Redis 层必须用 Lua 脚本保证原子性
不能只调 SETNX + EXPIRE 两步，中间存在竞态窗口。必须用一段 Lua 脚本一次性完成「判断是否存在 → 不存在则设 processing 并过期 → 返回状态码」。
推荐脚本逻辑：
if redis.call("EXISTS", KEYS[1]) == 0 then
redis.call("SETEX", KEYS[1], ARGV[1], ARGV[2])
return 1
else
local val = redis.call("GET", KEYS[1])
if val == "processing" then return 2 end
return 0
end
-
KEYS[1]是客户端传来的Idempotency-Key（如"idempotent:7f8c4a2e-1b3d-4e5f-8a9c-0e1d2f3a4b5c"） -
ARGV[1]设为 86400（24 小时），覆盖最长业务链路 + 重试窗口；太短会导致重试失败，太长会卡死异常中断的 key -
ARGV[2]固定为"processing"，避免空值误判为未处理 - 返回
1表示首次进入，可执行业务；0表示已有终态结果（成功/失败），直接返回缓存响应；2表示正在处理中，建议返回409 Conflict或阻塞等待
数据库唯一约束是最后一道不可绕过的防线
Redis 可能宕机、网络分区、或人为清理，不能作为唯一信任层。所有幂等写操作对应的业务表，必须增加字段并建唯一索引。
- 在订单表加列：
idempotency_key NVARCHAR(64) NOT NULL - 建唯一索引：
CREATE UNIQUE INDEX IX_Orders_IdempotencyKey ON Orders(idempotency_key) - 插入时不先查库（查-插之间有竞态），直接用
INSERT ... ON CONFLICT DO NOTHING（PostgreSQL）或MERGE（SQL Server） - 不要依赖 ORM 的“先查再 SaveChanges”，EF Core 的
ExecuteSqlRaw或 Dapper 的原生 SQL 更可控
文件操作的幂等性常被忽略但同样关键
File.Replace 不是幂等操作——它只做路径替换，不校验内容。两次调用传入不同源文件，会无条件覆盖目标，违反「相同输入 → 相同系统状态」原则。
- 正确做法是：先计算目标文件 SHA256 哈希（用
using var sha = SHA256.Create()，别复用静态实例） - 再计算源内容哈希，仅当两者不等时才写入
- 读目标文件要用
FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read)，否则被 IIS 或其他进程独占打开时直接抛IOException - 别比文件大小或最后修改时间——Windows 时间戳精度只有 10ms，且可被手动篡改
最易被跳过的点：Redis key 过期时间不是拍脑袋定的，得对齐业务最长耗时（比如支付回调可能长达 30 秒）+ 客户端最大重试间隔（如 5 秒 × 3 次 = 15 秒），再加冗余。少于这个值，重试请求会被当成新请求；大于这个值，异常中断的 key 会长期卡住后续合法请求。
