Redis HSETNX 为什么适合做幂等初始化：字段级写入与重复请求判断

订单服务第一次收到“创建支付记录”请求时，需要写入初始化状态；客户端超时后重试，不能因为重复写入又把已经确认的状态覆盖掉。Redis 的 HSETNX 正好把判断和写入合成一次字段级操作：返回 1 表示字段刚刚写入，返回 0 表示字段已经存在，调用方据此决定继续初始化还是读取现有结果。

HSETNX key field value 只在 Hash 字段不存在时写入；它适合做一次性初始化，但不等于完整的业务幂等方案，状态读取、过期策略和副作用仍要单独设计。

用一个订单 Hash 先跑通 HSETNX

假设订单号是 order:20260827:1001，初始化阶段只允许写入一次 init_token。先在 Redis CLI 中执行下面的命令：

HSETNX order:20260827:1001 init_token pay-7f3a
HGET order:20260827:1001 init_token
HSETNX order:20260827:1001 init_token pay-9c21
HGET order:20260827:1001 init_token

第一次 HSETNX 返回 1，HGET 得到 pay-7f3a；第二次返回 0，字段值仍是第一次写入的 pay-7f3a。这里的关键不是“命令执行成功”，而是第二次请求没有改变已有字段。

配图中的路径对应这段命令：请求先到 HSETNX，再根据返回值 1/0 分出首次初始化和重复请求两条结果；最终都可以用 HGET 检查实际保存的字段值。

HSETNX 判断的是字段，不是整个 Hash key

一个 Hash 可以同时保存多个初始化字段。例如 init_token 已存在，并不妨碍后续首次写入 payment_status：

HSETNX order:20260827:1001 payment_status pending
HEXISTS order:20260827:1001 init_token
HEXISTS order:20260827:1001 payment_status
HGETALL order:20260827:1001

HEXISTS 适合在排查时确认字段是否存在，但不要把“先 HEXISTS、再 HSET”当成并发安全的替代写法。两个客户端都先看到不存在时，仍可能同时进入写入分支；需要只允许一个客户端抢到初始化权时，直接使用 HSETNX 的返回值。

在 Go 代码里把返回值变成幂等分支

下面用 go-redis 风格的接口表达最小业务分支。HSetNX 返回布尔值，true 表示本次请求完成了字段初始化；false 表示字段早已存在，代码应读取旧值并返回已有结果。

created, err := rdb.HSetNX(ctx,
    "order:20260827:1001", "init_token", "pay-7f3a").Result()
if err != nil {
    return err
}
if !created {
    oldToken, err := rdb.HGet(ctx,
        "order:20260827:1001", "init_token").Result()
    if err != nil {
        return err
    }
    return useExistingToken(oldToken)
}
return startPayment("pay-7f3a")

这个分支只负责“谁完成初始化”的竞争，不负责支付接口本身的唯一执行。生产代码里还要让支付请求使用同一个业务幂等号，并在外部调用成功后更新 payment_status；否则 Redis 字段虽然只写了一次，外部副作用仍可能因网络重试重复发生。

TTL、空字符串和失败恢复要单独验收

HSETNX 不会自动给 Hash 或字段设置过期时间。若初始化记录只应保留一天，需要明确对整个 key 执行 EXPIRE order:20260827:1001 86400，并接受 key 过期后再次初始化的业务含义。Redis 版本支持 Hash 字段过期命令时，也应先确认线上版本和客户端支持情况，不能把 key TTL 与字段 TTL 混为一谈。

值为空字符串也算“字段已存在”：HSETNX order:20260827:1001 init_token "" 之后再次写入仍返回 0。如果空值代表初始化失败，就不要只靠字段存在性表达失败状态，可以把状态、错误原因和版本号设计成明确字段，并用状态机限制可接受的迁移。

常见问题：HSETNX 的边界怎么判断

HSETNX 能替代 SETNX 做整条键的幂等吗？

不能完全替代。SETNX 以整个 key 为单位，HSETNX 以 Hash field 为单位；选择哪一个取决于同一 key 下是否需要保存多个独立字段。

返回 0 是 Redis 出错了吗？

不是。返回 0 表示目标 field 已经存在，命令没有覆盖它；只有网络、类型冲突等异常才应按错误处理。

为什么不先 HEXISTS 再 HSET？

因为两个命令分开后会留下并发窗口。需要抢占一次初始化权时，直接检查 HSETNX 的返回值更可靠。

Hash key 过期后还能保证永不重复初始化吗？

不能。TTL 到期会删除整个 key，之后同一业务标识可能再次返回 1；幂等保留期必须覆盖允许的重试窗口，长期唯一性则需要持久化业务记录。

小结：把一次性写入和业务副作用分开

HSETNX 的价值很明确：在一个 Hash field 上用原子返回值区分“首次写入”和“已存在”。用 HGET 读取旧值、用 HEXISTS 做排查、用 TTL 管理保留期，就能把 Redis 层的状态证据补齐。至于支付、发货或消息发送等外部动作，还需要业务幂等号和可恢复状态共同兜底。