Redis 哈希字段怎么单独设置过期时间

Redis 7.4 及以上版本可以直接给 Hash 的单个字段设置过期时间。秒级相对过期使用 HEXPIRE，毫秒级相对过期使用 HPEXPIRE；检查剩余时间则分别使用 HTTL 和 HPTTL。这样，Hash 中的临时验证码可以自动删除，而昵称、偏好等长期字段继续保留。

官方文档：https://redis.io/docs/latest/commands/hexpire/

关键写法是：HEXPIRE key 秒数 FIELDS 字段数量 字段名...。过期对象是指定字段，不是整个 Hash key。

先确认版本和命令边界

HEXPIRE、HPEXPIRE、HTTL 和 HPTTL 从 Redis Open Source 7.4.0 开始提供。旧版本中的 EXPIRE 只能设置整个 key 的 TTL，不能只让 Hash 中某一个 field 到期。

先写入 Hash，再选择需要过期的字段

假设一个用户资料 Hash 同时保存长期字段和短期字段。昵称不应自动删除，验证码和一次性提示则需要独立过期。

# 写入同一个 Hash 的三个字段
redis-cli HSET user:42 nickname "Ava" verification_code "483921" feature_hint "new-ui"

# 查看当前字段和值，确认待设置 TTL 的字段已经存在
redis-cli HGETALL user:42

字段级 TTL 是附着在 field 上的生命周期信息。下图只说明 Hash、字段和 TTL 检查命令之间的静态关系，不是 Redis 控制台截图或运行证据。

用 HEXPIRE 设置秒级字段 TTL

下面让 verification_code 在 300 秒后删除，让 feature_hint 在 3600 秒后删除。FIELDS 后面的数字必须与随后给出的字段数量一致。

# 给一个字段设置 300 秒 TTL：FIELDS 1 表示后面只有一个字段名
redis-cli HEXPIRE user:42 300 FIELDS 1 verification_code

# 给另一个字段设置 3600 秒 TTL，不影响 nickname
redis-cli HEXPIRE user:42 3600 FIELDS 1 feature_hint

命令会按字段返回数组结果。每一项的含义是：1 表示已设置或更新过期时间，0 表示条件选项未满足，-2 表示字段或 key 不存在，2 表示 TTL 为零或绝对时间已过去，字段被立即删除。

一次也可以处理多个字段：

# 同时把两个临时字段的 TTL 更新为 600 秒
redis-cli HEXPIRE user:42 600 FIELDS 2 verification_code feature_hint

用 HTTL 或 HPTTL 核对结果

设置完成后不要只看命令是否成功，还要检查字段状态。HTTL 返回秒，HPTTL 返回毫秒；两者都按字段顺序返回数组。

# 按秒检查三个字段：长期字段应返回 -1，临时字段应返回正数
redis-cli HTTL user:42 FIELDS 3 nickname verification_code feature_hint

# 需要更细粒度时按毫秒检查验证码字段
redis-cli HPTTL user:42 FIELDS 1 verification_code

用条件选项控制 TTL 更新

NX、XX、GT、LT 互斥，一次只能选一个。它们按每个指定字段分别判断，因此批量设置时要逐项读取返回数组。

# 仅当验证码字段当前没有 TTL 时才设置
redis-cli HEXPIRE user:42 300 NX FIELDS 1 verification_code

# 仅当字段已经有 TTL 时才更新
redis-cli HEXPIRE user:42 600 XX FIELDS 1 verification_code

# 仅在新 TTL 更长时更新，避免意外缩短有效期
redis-cli HEXPIRE user:42 900 GT FIELDS 1 verification_code

# 仅在新 TTL 更短时更新，适合收紧临时数据窗口
redis-cli HEXPIRE user:42 120 LT FIELDS 1 verification_code

不带条件时，再次执行 HEXPIRE 会把已有 TTL 更新为新值。官方说明中，未设置过期的字段在 GT 比较时被视为无限 TTL，因此“只允许延长”的逻辑要先明确业务语义，不能机械套用。

字段从写入到清理的推荐流程

一个稳定的字段生命周期应同时覆盖写入、设置 TTL、查询 TTL、持久化和自动删除。不同命令对应的是字段状态关系，而不是整条 Hash key 的生命周期。

1. 先用 HSET 写入字段，避免对不存在字段设置 TTL 后只得到 -2。
2. 按业务精度选择 HEXPIRE 或 HPEXPIRE，并核对每个字段的返回值。
3. 用 HTTL 或 HPTTL 读取剩余时间，把 -1 和 -2 分开处理。
4. 字段要恢复长期保存时使用 HPERSIST，不要重新拼接整个 Hash。
5. 字段到期后确认业务能接受它单独消失，读取端不要把缺失字段误判为整个用户对象不存在。

HSET 覆盖字段会清除原 TTL

这是最容易踩的边界。官方文档说明，删除或覆盖字段内容的命令会清除字段过期信息，HDEL 和 HSET 都属于这一类。也就是说，给已有字段执行 HSET 写入新值后，需要按业务规则重新设置 TTL。

# 覆盖验证码值会清除该字段原有的过期信息
redis-cli HSET user:42 verification_code "771204"

# 覆盖后重新绑定 300 秒 TTL
redis-cli HEXPIRE user:42 300 FIELDS 1 verification_code

相反，只是在概念上修改字段内部数值而不是替换字段内容的操作，官方说明会保留 TTL。无论使用何种客户端，写入路径都应明确“这次操作是否替换了 field 值”，并把重新设置 TTL 纳入同一业务操作。

Redis 7.4 之前怎么设计

旧版本不能直接给 Hash field 设置 TTL。常见替代方案有两种：

• 拆成独立 key：例如把验证码写成 user:42:verification_code，然后对这个 key 使用 EXPIRE。结构简单，过期语义最直接。
• Hash 加有序集合索引：Hash 保存值，Sorted Set 用过期时间戳作为 score，后台任务扫描并执行 HDEL。适合必须保留聚合 Hash 的场景，但需要额外清理逻辑和一致性处理。

如果可以升级，Redis 7.4 的字段级过期命令通常比自建清理任务更直接。升级前仍应核对客户端库是否暴露对应命令；即使没有高级方法，也可以通过客户端的原生命令接口发送标准 Redis 命令。

常见误区与速查

• 把 EXPIRE 当成字段过期：它会影响整个 key，不是某个 Hash field。
• FIELDS 数量写错：数量必须和后续字段名个数一致。
• 忽略批量返回数组：同一命令中有的字段可能成功，有的可能不存在或条件不满足。
• 覆盖字段后不重设 TTL：HSET 覆盖会清除该字段的原过期信息。
• 把 -1 当成不存在：-1 是字段存在但没有 TTL；-2 才表示字段或 key 不存在。
• 在旧版本直接调用：服务端低于 7.4 时应使用替代建模，而不是只升级客户端。

小结：Redis Hash 字段单独过期的标准方案是 HEXPIRE 或 HPEXPIRE，设置后用 HTTL 或 HPTTL 核对。真正需要额外注意的是批量返回值、条件选项，以及 HSET 覆盖字段会清除原 TTL。