Redis HSETEX 怎么只在字段不存在时写入并设置过期

如果一个 Hash 字段只能在“第一次出现”时写入，同时还要设置字段级过期，以前常常要把判断、写入和过期拆成多步。Redis 8 提供的 HSETEX 可以把这件事收进一条命令：用 FNX 限定所有目标字段都不存在，再用 EX 或 PX 设置 TTL。

这篇只解决一个边界明确的问题：Redis HSETEX 怎样只创建不存在的字段并设置过期。核心判断是返回值 1 代表全部字段写入，0 代表条件没有满足、没有字段被设置。

官方地址：https://redis.io/docs/latest/commands/hsetex/

适用前提：HSETEX 自 Redis Open Source 8.0.0 提供；如果服务端版本更低，应先确认是否支持该命令。

先把 HSETEX 的参数边界看清楚

HSETEX 的结构可以记成：key + 条件 + 过期策略 + FIELDS 字段对。例如下面的命令尝试给 session:42 写入两个字段，只有 profile 和 trace 都不存在时才成功，并让它们各自保留 60 秒。

# 中文注释：FNX 要求本次列出的所有字段都不存在，EX 60 设置字段级秒数 TTL
redis-cli HSETEX session:42 FNX EX 60 FIELDS 2 profile "basic" trace "enabled"

FIELDS 2 中的数字是字段数量，后面必须跟两组 field/value。它不是“最多写两个”的限制，而是告诉 Redis 后续有多少组字段值。过期策略可以换成 PX、EXAT 或 PXAT，但 EX、PX、EXAT、PXAT 和 KEEPTTL 只能选一个。

FNX 的关键是“全部字段一起判断”

最容易误解的地方是：FNX 不是“哪个字段不存在就写哪个”。Redis 官方定义是，只有当本次列出的字段全部不存在时才设置；只要其中一个已经存在，本次就不写入这些字段。这个全量条件适合初始化一组必须同时出现的摘要字段。

# 中文注释：第一次调用成功时返回 1，并同时建立两个带 TTL 的字段
redis-cli HSETEX session:42 FNX EX 60 FIELDS 2 profile "basic" trace "enabled"

# 中文注释：再次提交同一组字段时，FNX 条件不满足，返回 0
redis-cli HSETEX session:42 FNX EX 60 FIELDS 2 profile "premium" trace "disabled"

第二次调用不会只更新 profile，也不会只跳过已经存在的字段。它的结果是整组条件失败。因此，如果业务要求“逐字段尽量写入”，就不应把 FNX 当成批量过滤器；本文不把那个需求扩展成另一套策略。

用返回值和 HTTL 判断是否写入

HSETEX 的返回值比重新读取字段更适合作为这次写入的直接结果：1 表示所有字段都设置成功，0 表示没有字段被设置。写入成功后，再用 HTTL 按字段读取剩余秒数。

# 中文注释：按字段查看剩余 TTL，返回值顺序与字段参数顺序对应
redis-cli HTTL session:42 FIELDS 2 profile trace

# 中文注释：只读取字段值，用于展示初始化后的数据，不把读取当成条件判断
redis-cli HMGET session:42 profile trace

如果命令返回 0，不要把它解释成“字段值被清空”或“TTL 被刷新”。它表示这次没有字段被设置。若需要区分字段是否存在，可以再按业务需要读取，但不要用一次普通读取替代 FNX 的原子条件。

迁移时最容易踩到的三个边界

第一，确认服务端版本。HSETEX 是 Redis Open Source 8.0.0 才提供的命令，客户端能拼出命令文本，不代表服务端一定支持。

第二，别混用过期参数。下面这种写法会因为同时给出 EX 和 KEEPTTL 而报参数冲突：

# 中文注释：同一条 HSETEX 只能选择一种过期策略，这里故意展示互斥参数
redis-cli HSETEX session:42 FXX EX 60 KEEPTTL FIELDS 2 profile "basic" trace "enabled"

第三，分清字段 TTL 和 Hash key TTL。HSETEX 设置的是字段级过期；不要拿整键 TTL 的思路去解释它。检查字段时使用 HTTL、HPTTL 等对应命令，并保持字段列表顺序一致。

最后记住这条最小写法

需要“字段首次出现才写入，并且成功后自动过期”时，最小主路径就是：

# 中文注释：全部字段不存在才一次性创建，成功后每个字段保留 60 秒
redis-cli HSETEX session:42 FNX EX 60 FIELDS 2 profile "basic" trace "enabled"

判断流程也保持简单：看返回值是否为 1，再用 HTTL key FIELDS ... 观察字段级 TTL。不要把 FNX 理解成逐字段 upsert，也不要同时传入两种过期策略。

相关问题

HSETEX 的 FNX 和 FXX 能同时使用吗？不能。两者互斥，FNX 要求字段全部不存在，FXX 要求字段全部存在。

HSETEX 能用毫秒级过期吗？可以，用 PX；绝对时间则使用 EXAT 或 PXAT，但这些过期选项不能同时出现。

返回 0 时会不会只写入一部分字段？按 FNX 的全量条件，返回 0 表示没有字段被设置，不能把它当作部分成功。