fiber未提供开箱即用幂等中间件，因其轻量设计哲学拒绝封装业务语义；必须手动组合redis与中间件实现唯一标识提取、原子写入、响应复用三步逻辑，并辅以db唯一索引兜底。
没有现成的官方 Idempotency 中间件，Fiber 本身不内置幂等性支持，必须自己组合 Redis + 中间件逻辑来实现 —— 这和 Spring Boot 的 @Idempotent 注解方案完全不同。
为什么 Fiber 没有开箱即用的幂等中间件
Fiber 是轻量级 Go Web 框架，设计哲学是“不打包业务逻辑”，所有中间件都聚焦于路由、日志、CORS 等通用能力。幂等性涉及业务语义（比如 key 怎么生成、失败怎么返回、状态怎么存），无法抽象成通用中间件。你看到的某些第三方 fiber-idempotency 包，往往只做最简 SETNX 占位，不处理重试响应复用、状态回滚、Redis 故障降级等真实场景问题。
- 它不关心你是创建订单、发券还是支付回调 —— 这些决定了幂等 key 的构成
- 它不帮你决定：重复请求来了，是返回 409 Conflict，还是返回第一次成功时的订单号和 JSON？
- 它默认信任 Redis 可用且 TTL 不会提前失效 —— 但线上 Redis 故障、主从切换丢 key 是常态
手动实现幂等中间件的关键三步
核心逻辑就是：提取唯一标识 → 查 Redis → 若存在则复用结果，否则执行业务并写入记录。下面以创建订单为例：
-
幂等 key 必须含业务上下文：不能只用客户端传的
idempotency-keyHeader，得拼上tenant_id、user_id和接口路径，例如"order:create:tenant_123:user_456:" + header["Idempotency-Key"] -
Redis 写入必须带原子性和 TTL：用
SET key value EX 300 NX，300 秒要覆盖整个业务链路耗时（包括 DB 提交、MQ 发送、回调通知） -
重复请求必须返回原始响应快照：首次成功后，把 HTTP 状态码、body、header 序列化存 Redis；后续命中直接
c.Status(code).SendString(body)，而不是简单 return error
容易踩的坑：Redis 占位成功但业务失败怎么办
这是最常被忽略的故障窗口：Redis SETNX 成功 → 业务 panic 或 DB 插入失败 → Redis key 滞留 → 后续请求全被拦截为“已存在”，但其实根本没成功。
- 必须在中间件里加 defer recover，捕获 panic 后主动
DEL对应 key - 业务函数返回 error 时，不能只 log，得显式调用
redis.Del(ctx, key) - 更稳妥的做法是：Redis 初始存
"PROCESSING"，成功后再SET为完整响应；失败则DEL，避免残留脏状态 - 别依赖单次
SETNX—— 要配合 Lua 脚本做“检查+设置+超时”三合一原子操作，否则并发下仍有竞争
要不要加数据库唯一索引作为兜底
要，而且必须加。Redis 是前置挡板，不是最终一致性保障。
- 订单表加联合唯一索引：
UNIQUE KEY idx_idempotency (tenant_id, user_id, idempotency_key) - 插入时用
INSERT ... ON CONFLICT DO NOTHING（PostgreSQL）或INSERT IGNORE（MySQL），避免因 Redis 失效导致重复落库 - 如果 DB 唯一索引冲突，说明 Redis 挡漏了，这时应查 Redis 是否有成功响应缓存；没有就走新流程，有就复用 —— 这才是“重复得到一致结果”的工程实践
真正难的不是写中间件，而是定义清楚每个接口的幂等边界：key 怎么切分、TTL 设多长、失败怎么清理、重试响应怎么序列化。这些没法靠一个中间件自动推导，得逐个接口对齐业务语义。
