Redis HPEXPIRE 怎样给 hash 单个字段设置毫秒过期

如果一个 Redis hash 里同时放着会话、验证码和配额，直接给整个 key 设置过期时间往往太粗。Redis 7.4 及以上可以用 HPEXPIRE 只给某个字段设置毫秒级 TTL：先写入字段，再执行 HPEXPIRE profile:1001 60000 FIELDS 1 session，最后用 HPTTL 读取剩余毫秒数。

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

HPEXPIRE 的核心用法：只给 hash 的一个字段设置毫秒 TTL

命令的基本形态是 HPEXPIRE key milliseconds FIELDS numfields field...。例如只让 session 保留 60 秒，而同一个 hash 中的 quota 和 nickname 不跟着过期：

# 先准备同一个 hash 的多个字段，便于观察字段级过期
redis-cli HSET profile:1001 session abc123 quota 8 nickname li

# 只给 session 设置 60000 毫秒的相对过期时间
redis-cli HPEXPIRE profile:1001 60000 FIELDS 1 session

# 同一次命令也可以处理多个字段，FIELDS 后的数字必须匹配字段数量
redis-cli HPEXPIRE profile:1001 120000 FIELDS 2 quota nickname

返回值按字段排列：成功设置通常返回 1，字段不存在时返回 0。这里的“字段过期”是 hash 内部的元数据，不是把 profile:1001 拆成多个 Redis key。

NX、XX、GT、LT 如何选择过期更新策略

不带条件时，命令会按本次参数设置或更新字段 TTL。生产代码更适合把更新意图写出来：首次写入用 NX，只延长已有 TTL 时用 GT，只缩短时用 LT，而 XX 用来防止给没有现有 TTL 的字段加过期。

四个条件互斥，不能同时写。我的经验是，续期接口优先考虑 GT：它能避免一个较旧的请求把更长的 TTL 覆盖掉；但如果业务要求每次登录都严格重置为固定时长，就不要额外套 GT。

用 HPTTL 判断设置是否生效

设置后不要只看命令返回值，使用 HPTTL 读取指定字段的剩余毫秒数：

# 查询 session 的字段级剩余 TTL；返回值会随时间减少
redis-cli HPTTL profile:1001 FIELDS 1 session

# 查询多个字段，返回顺序与字段参数顺序一致
redis-cli HPTTL profile:1001 FIELDS 2 session quota

返回负数时要结合语义判断：-1 通常表示字段存在但没有 TTL，-2 表示字段或 key 不存在。需要绝对时间点时使用 HPEXPIRETIME，不要把 HPTTL 的剩余时长当成 Unix 时间戳。

字段过期与 key 过期的边界

HPEXPIRE 只对已经存在的 hash 字段生效，不负责创建字段；因此常见顺序是先 HSET，再设置 TTL。字段自然过期后，读取该字段会像字段不存在一样，hash 中其他字段仍可保留。

还要确认服务端版本至少支持 Redis 7.4。旧版本不能把这条命令当作普通 PEXPIRE 的别名；如果业务必须兼容旧 Redis，只能退回“每个会过期值一个 key”或在应用层维护过期时间的模型。最后区分两层生命周期：PEXPIRE profile:1001 ... 管的是整个 hash，HPEXPIRE ... FIELDS ... 管的是字段，两者可以同时存在，但 key 先过期时字段级 TTL 就没有单独意义了。

相关问题

HPEXPIRE 为什么返回 0？

先检查 key 和字段是否存在，再检查是否带了 NX、XX、GT 或 LT。条件不满足时，即使命令语法正确，也可能不会设置。

能不能只给 hash 的一个字段设置秒级过期？

可以使用 HEXPIRE；需要毫秒精度时使用本文的 HPEXPIRE，两者的字段选择语法相同。

HPTTL 查不到字段级过期怎么办？

确认字段不是刚被删除、key 没有整体过期，并检查 HPTTL 的 FIELDS 数量和字段名是否对应；字段存在但未设置 TTL 时会得到无过期语义的返回值。