C# Web API 幂等性必须由后端兜底，主流方案包括：Idempotency-Key + 分布式缓存校验、数据库唯一约束、Token 机制、乐观锁 version 字段，并需混合使用与注意缓存清理和上下文透传。
不用前端防抖，也不靠用户不点两次——C# Web API 的幂等性必须由后端兜底，否则订单重复、支付多扣、库存错减就是分分钟的事。
Idempotency-Key + 分布式缓存校验（最常用且可控）
这是目前生产环境最主流的做法：客户端在请求头带上 Idempotency-Key（如 X-Idempotency-Key: 8a9e4b2c-1f3d-4a5e-9b7c-d1e2f3a4b5c6），服务端用它查缓存，已存在就直接返回历史响应，不再执行业务逻辑。
- 缓存必须是分布式（如 Redis），不能用
ConcurrentDictionary—— 多实例部署下会失效 - 缓存 Key 建议组合：前缀 +
Idempotency-Key+ HTTP 方法 + 路径（避免不同接口误判） - 缓存值要存完整响应体 + 状态码 + 时间戳，且设合理过期（如 24 小时），避免无限膨胀
- 注意：若业务要求“失败也幂等”，需缓存失败结果；否则只缓存成功响应，失败请求仍可重试
数据库唯一约束兜底（强一致性场景首选）
当业务天然有唯一业务键（如订单号 orderNo、支付流水号 tradeNo），直接在数据库加 UNIQUE INDEX 是最硬核的防线。
- 建表时必须用业务字段建唯一索引，例如：
CREATE UNIQUE INDEX uq_order_no ON Orders(orderNo) - 插入前不查、不预判，直接
INSERT，捕获SqlException中的唯一约束错误码（SQL Server 是 2627/2601，MySQL 是 1062） - 捕获后不要简单吞掉异常——要判断是否真因重复导致，并返回对应语义（如
409 Conflict或复用原记录） - 慎用于高并发写入场景：唯一索引冲突会引发锁等待，可能拖慢整体吞吐
Token 机制生成 + 消费校验（适合表单类交互）
不是所有客户端都能带 Idempotency-Key，比如传统 HTML 表单。这时用 Token 机制更自然：先 GET 一个 token，再 POST 时带上它，服务端消费即失效。
- Token 必须一次性使用，生成后存 Redis，Key 为 token 字符串，Value 可为空或含基础元数据（如关联用户 ID、过期时间）
- POST 接口收到 token 后，先
DEL它，成功才继续处理；DEL返回 0 表示已被消费，直接拒绝 - Token 过期时间建议 5–15 分钟，太短影响用户体验，太长增加被撞库风险
- 别把 token 放在 URL 里传——会被日志、代理、Referer 泄露；务必走
Authorization或自定义 Header
乐观锁 version 字段（仅适用于更新类操作）
对「修改」而非「创建」的接口，乐观锁是轻量又可靠的方案：每次更新都校验当前版本号是否匹配，不匹配就拒绝。
- 数据库表必须加
version列（INT或TIMESTAMP），初始值为 1 或当前时间 - UPDATE 语句必须包含
WHERE version = @expectedVersion，并检查RowsAffected == 1 - C# 层不能只靠 EF Core 的
ConcurrencyCheck特性——它只在校验失败时抛异常，但你得自己捕获并返回明确提示（如412 Precondition Failed） - 注意：乐观锁无法防止首次创建重复，它只管“改”，不管“增”
真正难的不是选哪种方案，而是混合使用——比如订单创建用唯一约束 + Idempotency-Key 双保险，库存扣减用乐观锁 + Redis 计数器兜底。最容易被忽略的是缓存清理时机和跨服务调用时的幂等上下文透传，这两处一漏，整条链路就白做了。
