【背景】 做了 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}") 注解，框架负责存储/比对/超时清理，业务只声明「用什么字段做键、窗口多长」。（Spring Cloud Gateway 的 RequestRateLimiter 或 Resilience4j 的 TimeLimiter 都不是幂等，别混用；真正的幂等模板需要自己封装 IdempotencyInterceptor，核心逻辑就 30 行：SETNX key result TTL → 命中则回放 result，未命中则执行 + SET。）
- 优点：兼顾一致性与粒度；
- 坑：注解表达能力有限，遇到「先查后写」的复合幂等就表达不了；而且注解的「隐式行为」对新人不友好——一个方法有没有幂等保护，要看注解，不看代码逻辑，review 时容易漏。
【我的倾向与理由】 我倾向 C + 一条硬规则：
- 框架/SDK 提供幂等模板（存储、比对、TTL 清理、冲突响应码统一 409），业务通过声明式注解或配置声明键语义和窗口；
- 硬规则：所有写接口必须在「接口契约」（OpenAPI / 内部 IDL）里显式声明幂等键字段，没有声明的写接口 CI 直接卡住不允许上线。这条不是技术决策，是流程决策，但它是真正防住「新接口默认无幂等」的那道闸。
- 存储层用 Redis + 本地 DB 双写兜底（Redis 挂了降级到 DB 唯一索引），TTL 至少覆盖「上游最大重试窗口 × 2」，别拍 7 天。
理由：幂等的本质是「对同一业务意图的重复执行只生效一次」，这个语义只有业务能定义；但「怎么存储、怎么比对、冲突怎么响应」是纯工程问题，不应该让 30 个团队各写一遍。把「语义」留给业务、把「机制」收归框架，是中间件团队最该占住的位置。
【新增：TTL 推导与一个真实事故】 上面第 3 条「TTL ≥ 上游最大重试窗口 × 2」不是拍脑袋，推导如下：
设上游重试策略为：最大重试次数 N，每次重试间隔为 backoff（指数退避，base=1s，max=30s），则：
- 上游「从首次请求到最后一次重试」的最大时间跨度 =
max_retries × max_backoff（保守上界，实际是指数退避累加，但工程上取上界更安全） - 例：N=5, max_backoff=30s → 最大跨度 ≈ 5×30 = 150s
- TTL 必须 > 最大跨度，否则最后一次重试到达时 Redis key 已过期，幂等失效
- ×2 的余量：覆盖「上游时钟漂移 + 网络 RTT + 服务端处理耗时」——我们见过一次上游 SDK 的 backoff timer 在 GC STW 后延迟 45s 才发出重试，恰好落在 TTL 边缘
真实事故（已脱敏）：某支付网关对接第三方渠道，渠道文档写「失败后重试 3 次，间隔 10s/30s/60s」，最大跨度 = 10+30+60 = 100s。我们最初 TTL 设了 120s（只比最大跨度大 20s）。某次渠道侧 GC 导致第二次重试延迟了 95s（远超文档的 30s），此时距首次请求已过 105s + 95s = 200s > 120s TTL → Redis key 已过期 → 幂等失效 → 同一笔扣款执行了 2 次。对账 T+1 才发现，涉及 37 笔交易，手动冲正花了 2 人天。事后把 TTL 改为 max_span × 2 = 200s，再没出过。
教训：TTL 的安全系数不是 ×1.2，至少 ×2；而且「上游文档写的重试策略」和「上游 SDK 实际行为」经常不一致，审计时要把对方 SDK 源码翻一遍。
【想听大家怎么选】 想收集几个具体场景下的做法，欢迎对号入座：
- 你的幂等键是请求级（一次 HTTP 调用）还是业务级（一笔订单）？怎么在同一个接口里同时支持「合法重试」和「防重复提交」？
- 幂等结果存储用 Redis、DB 唯一索引、还是 Kafka 去重？TTL 怎么定的，有没有踩过「TTL 太短导致窗口外重放」的坑？
- 如果上游没带幂等键（老客户端 / 第三方回调），你是拒绝（400）、网关生成一个（但语义可能错）、还是放行（裸奔）？
- 幂等冲突的响应码你们统一用 409、200+业务码、还是 500？有没有因为响应码不统一导致客户端重试逻辑翻车的？
- 有没有「幂等键本身成为故障源」的经历？（比如 Redis 集群分裂期间 SETNX 行为不一致、DB 唯一索引在高并发下死锁）
期待听到不同规模团队（5 个服务 vs 500 个服务）在这件事上的取舍差异。