Hyperf中Redis实现接口幂等性的核心是用set(NX+EX)原子判断请求是否已执行，而非加锁；需对X-Idempotency-Key做md5或HMAC标准化处理、带业务前缀，且必须缓存完整响应（status/body/headers），TTL应设为略大于业务最长处理时间（如30秒）以避免脏数据残留。
Hyperf 中用 Redis 实现接口幂等性，核心不是“锁住整个请求”，而是“用原子操作判断并记录请求是否已执行”。直接上 setnx 加过期时间是最常用且够用的方案，但很多人在 Redis::set 参数、key 设计、并发边界上栽跟头。
为什么不用 Redis::lock 而用 set 带 NX 和 EX
Hyperf 的 Redis::lock 是封装过的分布式锁（基于 Lua + set），适合长时业务加锁；幂等性场景要求轻量、快速、一次判定，用原生命令更可控：
-
Redis::set($key, $value, ['NX', 'EX' => 86400])是原子操作，成功即代表“首次录入”，失败说明已被处理过 -
Redis::lock会额外做续期、释放校验，增加延迟和复杂度，对幂等性属于过度设计 - 如果真要用
lock，必须手动unlock，否则锁残留会导致后续所有同 key 请求被阻塞——这不是幂等，是限流
X-Idempotency-Key 怎么生成才安全
客户端传来的 X-Idempotency-Key 不能直接拼进 Redis key，否则可能引入控制字符、超长 key 或注入风险：
- 必须做标准化处理：比如
md5($rawKey)或base64_encode(hash_hmac('sha256', $rawKey, $secret)) - 避免用用户可控字段（如手机号、订单号）直接作 key，防止恶意构造相同 key 碰撞不同业务
- 建议服务端生成并返回 key（如防重 Token 流程），而非完全依赖客户端——客户端可能复用旧 key 或伪造
- key 前缀要带业务标识，例如
idempotency:order:create:，避免跨接口污染
缓存响应体时，status 和 headers 必须一起存
只缓存 JSON body 会导致状态码丢失，比如第一次是 201 Created，第二次返回 200 OK，违反幂等语义：
- 必须把完整响应结构序列化存储，例如：
json_encode(['status' => 201, 'body' => [...], 'headers' => ['X-Idempotency-Replayed' => 'true']]) - 注意
ResponseInterface不可直接序列化，需提前提取关键字段 - 若响应体较大（>10KB），不建议全量缓存，改用“结果 ID + 异步查库”模式，否则 Redis 内存压力陡增
- 不要用
Redis::hSet分字段存，get+json_decode一次取回更简单可靠
真正容易被忽略的是“锁失效窗口”：当请求刚写入 Redis，还没来得及执行业务就崩溃了，这个 key 会残留 24 小时。所以 TTL 不能无脑设大，要结合业务最长处理时间（比如支付回调最多 5 秒），设成 EX => 30 更稳妥——既防误删，也不留太久脏数据。
