iris框架本身不内置幂等性校验，必须结合redis+唯一请求标识手动实现，核心是“先查后写”与原子性标记；因其设计哲学聚焦能力提供而非业务封装，故无开箱即用的幂等中间件。
直接结论：Iris 框架本身不内置幂等性校验，必须结合 Redis（或其他共享存储）+ 请求唯一标识（如 Idempotency-Key 或业务 ID）手动实现。核心是「先查后写」+ 「原子性标记」，否则容易漏判或误判。
为什么 Iris 没有现成的幂等中间件
Iris 是轻量级高性能 Web 框架，设计哲学偏向“提供能力而非封装业务逻辑”。它提供了完整的中间件机制、上下文控制、Redis 集成支持（iris.Redis()），但像幂等性这种强业务语义的逻辑，官方不会抽象成开箱即用组件——因为判断依据（用什么做 key？过期多久？失败怎么清理？）高度依赖场景。
常见错误是试图找 iris.UseIdempotent() 这类函数，结果发现不存在。别浪费时间翻源码找隐藏 API，得自己搭骨架。
关键步骤：从请求头提取 Idempotency-Key 并校验
主流做法是客户端在请求头带上 Idempotency-Key（RFC Draft 规范用法），服务端据此做去重。注意不是所有客户端都守规矩，所以得兼容 fallback 策略：
- 优先读取请求头
Idempotency-Key字段；若为空，尝试从 JSON body 解析idempotency_key字段（需提前解析 body） - 若仍为空，可退化为用业务字段组合生成（例如
user_id:order_id），但必须确保该组合在业务上天然唯一且不可篡改 - 校验逻辑必须包裹在 Redis 的
SET key value EX 3600 NX原子操作中，不能先GET再SET—— 否则并发请求会同时通过检查 - 如果
SET返回false（即 key 已存在），直接返回409 Conflict或复用前次响应（后者需额外缓存响应体，慎用）
Redis 存储结构与过期时间怎么设
幂等记录本质是「状态快照」，不是长期数据，必须设 TTL：
- key 格式建议：
idempotent:{Idempotency-Key}，避免和其他 Redis key 冲突 - value 可存空字符串，或写入当前时间戳 + 请求路径（用于排查），但不要存完整 body（体积大、序列化开销高）
- TTL 推荐 24–72 小时，取决于业务重试窗口。支付类接口建议至少 48 小时（银行侧回调可能延迟）；普通表单提交 24 小时足够
- 切忌设永不过期（
SET key val无EX）—— 会缓慢吃光 Redis 内存，且无法自动清理历史脏数据
事务失败后如何清理幂等标记
这是最容易被忽略的坑：如果业务逻辑执行失败（比如数据库插入异常），但 Redis 已成功写入幂等 key，下次带相同 key 的请求会被直接拦截，导致「假成功」。
正确做法只有两种：
- 业务逻辑全部成功后再写入 Redis key（风险：若写 Redis 失败，重复请求仍会进入业务层）
- 更稳妥的是「两阶段」：先用
SET idempotent:{k} pending EX 300 NX占位（5 分钟超时），业务执行完再用SET idempotent:{k} success EX 86400覆盖；若失败，则不做覆盖，5 分钟后自动释放，允许重试 - 绝对不要在 defer 中删 key —— panic 或进程退出时不一定触发，且并发下删错 key 风险极高
复杂点在于：幂等性不是独立模块，它和你的业务错误处理、日志追踪、补偿机制深度耦合。比如支付回调幂等失败，不仅要返回 HTTP 状态，还得记录到审计表并触发告警。这些没法靠一个中间件解决，得在 handler 里显式编排。
