幂等键到底谁生成、谁校验、谁存储：「框架统一注入」vs「业务各自实现」，你们线上是哪种？踩过什么坑？

【背景】 做了 15 年中间件，最近帮一个 30+ 微服务团队做幂等审计，发现一个很典型的「规范写在文档里、实现散落在代码里」的状态：

• 网关层有一篇《幂等接入指南》wiki，要求所有写接口带 X-Idempotency-Key 头；
• 实际抽查 40 个写接口，只有 11 个真在消费这个头，另外 29 个各自为政：有的在业务表里建了 biz_id + client_id 唯一索引，有的用 Redis SETNX + 7 天 TTL，有的直接「信任上游不重发」；
• 最离谱的是一个支付回调接口，幂等键是「上游消息 ID + 处理时间戳秒」——上游重发同一笔消息时，跨了秒级边界就重复入账了，靠月底对账才发现。

这不是个例。幂等这种横切关注点，「谁负责」这件事在很多团队从来没被正式决策过，而是随第一个接入的业务代码「长」出来的。

【常见分歧 / 几种做法】 我梳理了一下常见的三种架构，各有代价：

做法 A：共享 SDK / 中间件层统一做（推荐派） 网关或 Filter 拦截，校验 X-Idempotency-Key 头 → Redis SETNX → 通过后注入上下文 → 业务无感。

• 优点：强制一致、新接口默认有保护、审计方便；
• 坑：SDK 升级要全量发布（我们遇到过一次 SDK 改 key 前缀，灰度期新旧并存，导致同一请求在旧节点 SETNX 成功、在新节点 SETNX 失败，双写）；另外「统一」容易变成「一刀切」——不同业务的幂等粒度差异很大（订单创建是请求级、支付回调是业务级、消息消费是消息级），一个 Redis key 模板很难覆盖。

做法 B：业务层各自实现（现实派） 每个接口自己定义幂等键语义、自己存储。

• 优点：粒度精确、贴合业务、没有 SDK 耦合；
• 坑：就是上面审计看到的那种散乱——每个团队一套实现，质量取决于写那个接口的人的功力，人员流动后没人敢动。

做法 C：折中——框架提供「幂等模板」+ 业务声明键语义 类似 Spring 的 @Idempotent(key = "order:#{#request.orderId}") 注解，框架负责存储/比对/超时清理，业务只声明「用什么字段做键、窗口多长」。

• 优点：兼顾一致性与粒度；
• 坑：注解表达能力有限，遇到「先查后写」的复合幂等就表达不了；而且注解的「隐式行为」对新人不友好——一个方法有没有幂等保护，要看注解，不看代码逻辑，review 时容易漏。

【我的倾向与理由】 我倾向 C + 一条硬规则：

1. 框架/SDK 提供幂等模板（存储、比对、TTL 清理、冲突响应码统一 409），业务通过声明式注解或配置声明键语义和窗口；
2. 硬规则：所有写接口必须在「接口契约」（OpenAPI / 内部 IDL）里显式声明幂等键字段，没有声明的写接口 CI 直接卡住不允许上线。这条不是技术决策，是流程决策，但它是真正防住「新接口默认无幂等」的那道闸。
3. 存储层用 Redis + 本地 DB 双写兜底（Redis 挂了降级到 DB 唯一索引），TTL 至少覆盖「上游最大重试窗口 × 2」，别拍 7 天。

理由：幂等的本质是「对同一业务意图的重复执行只生效一次」，这个语义只有业务能定义；但「怎么存储、怎么比对、冲突怎么响应」是纯工程问题，不应该让 30 个团队各写一遍。把「语义」留给业务、把「机制」收归框架，是中间件团队最该占住的位置。

【想听大家怎么选】 想收集几个具体场景下的做法，欢迎对号入座：

1. 你的幂等键是请求级（一次 HTTP 调用）还是业务级（一笔订单）？怎么在同一个接口里同时支持「合法重试」和「防重复提交」？
2. 幂等结果存储用 Redis、DB 唯一索引、还是 Kafka 去重？TTL 怎么定的，有没有踩过「TTL 太短导致窗口外重放」的坑？
3. 如果上游没带幂等键（老客户端 / 第三方回调），你是拒绝（400）、网关生成一个（但语义可能错）、还是放行（裸奔）？
4. 幂等冲突的响应码你们统一用 409、200+业务码、还是 500？有没有因为响应码不统一导致客户端重试逻辑翻车的？
5. 有没有「幂等键本身成为故障源」的经历？（比如 Redis 集群分裂期间 SETNX 行为不一致、DB 唯一索引在高并发下死锁）

期待听到不同规模团队（5 个服务 vs 500 个服务）在这件事上的取舍差异。