Redis Hash 字段独立过期怎么设置

Redis Hash 以前只能对整个 key 设置过期时间，不能直接让同一个 Hash 中的字段分别倒计时。Redis 7.4 开始可以用 HEXPIRE、HPEXPIRE 等字段过期命令完成这件事：先用 HSET 写入字段，再把 TTL 绑定到需要过期的字段；其他字段不会因为其中一个字段到期而一起消失。

先确认 Redis 版本和过期对象

这项能力的第一个风险是命令支持范围。HEXPIRE、HTTL 等字段级过期命令从 Redis 7.4 开始提供，因此不能只看客户端库是否有同名方法，还要确认实际服务端版本。另一个容易混淆的点是对象层级：EXPIRE user:1001 3600 会让整个 Hash 消失，而字段 TTL 只删除到期字段。

# 先确认服务端版本，再准备两个生命周期不同的字段
redis-cli INFO server | grep '^redis_version:'
redis-cli HSET user:1001 profile '基础资料' temp_token '一次性令牌'

# 只给 temp_token 设置 60 秒，profile 不会同时获得这个 TTL
redis-cli HEXPIRE user:1001 60 FIELDS 1 temp_token

如果服务端低于 7.4，执行 HEXPIRE 会得到未知命令或不兼容错误。此时不要把整个 Hash 的 EXPIRE 当成等价替代，因为它会扩大删除范围。

用 HEXPIRE 给指定 Hash 字段设置 TTL

HEXPIRE 的格式是 HEXPIRE key seconds FIELDS numfields field...。numfields 必须和后面的字段数量一致，多个字段可以一次提交同一个秒数。命令返回一个数组，并且返回值顺序与字段参数一一对应。

# 创建三类字段：资料长期保留，验证码和临时标记按需过期
redis-cli HSET login:1001 profile 'normal' verify_code '835421' device_hint 'ios'

# verify_code 5 分钟过期，device_hint 1 小时过期
redis-cli HEXPIRE login:1001 300 FIELDS 1 verify_code
redis-cli HEXPIRE login:1001 3600 FIELDS 1 device_hint

# 返回数组按字段对应：1=设置或更新成功，-2=字段不存在
redis-cli HEXPIRE login:1001 300 FIELDS 2 verify_code missing_field

最后一条命令通常会返回 1 和 -2。如果 TTL 为 0，字段会立即删除并返回 2；因此生产代码应记录每个字段的结果，不要只判断命令是否没有抛错。

用 HTTL 检查设置结果和异常状态

设置过期只是第一步，缓存命中、续期和排障都需要读取剩余时间。HTTL 的格式同样包含 FIELDS 和字段数量：正数表示剩余秒数，-1 表示字段存在但没有过期时间，-2 表示字段或 Hash 不存在。

# 同时检查两个字段，返回值顺序与参数顺序一致
redis-cli HTTL login:1001 FIELDS 2 verify_code profile

# 毫秒级场景使用 HPTTL；例如短时令牌比秒级 TTL 更容易精确控制
redis-cli HPTTL login:1001 FIELDS 2 verify_code device_hint

# 到期后读取字段，应该只剩下未到期的字段
redis-cli HGETALL login:1001

不要用普通的 TTL login:1001 证明字段 TTL 已生效，它查询的是整个 key 的过期时间。字段级过期和 key 级过期可以同时存在，但两者的删除范围不同，监控指标也应分开记录。

更新字段时的安全边界和兼容方案

字段过期不是一次性标签。Redis 文档说明，删除或覆盖字段内容的操作会清除该字段原有 TTL；因此业务在刷新验证码、会话状态或设备提示时，通常要把写入和重新设置 TTL 放在同一条业务路径中。只修改字段的值而忘记重新过期，会把临时数据意外变成永久数据。

如果业务确实需要兼容旧版本，常见做法是把 login:1001 拆成 login:1001:profile、login:1001:verify_code 等独立 key，再分别使用 EXPIRE。这种模型牺牲了 Hash 的一次读取便利，但生命周期边界更明确，迁移时也容易做灰度。

常见问题

Redis Hash 字段设置 TTL 后，整个 Hash 会消失吗？

不会。字段到期后只删除该字段；当 Hash 中已经没有字段时，整个 key 才可能随之被清理。

为什么 HEXPIRE 返回 -2？

通常是字段名写错、字段尚未 HSET，或 Hash key 本身不存在。先用 HEXISTS 检查字段，再按返回数组逐项处理。

给字段重新 HSET 后 TTL 还在吗？

不要假设还在。覆盖字段内容会清除该字段的过期设置，写入临时数据后应重新调用 HEXPIRE，并用 HTTL 复查。