Hash 字段过期怎么配置或排查

Redis Hash 的过期时间默认是 key 级别的，不能用一条 EXPIRE 让同一个 Hash 里的字段分别倒计时。Redis 7.4.0 起可以用 HEXPIRE（秒）或 HPEXPIRE（毫秒）给字段单独设置 TTL；排查时再用 HTTL 或 HPTTL 读取剩余时间。

如果字段过期“不生效”，先确认服务端至少是 Redis 7.4，再确认字段已经存在、HEXPIRE 的 FIELDS 数量和字段名正确，最后用 TTL 返回值判断是没有 TTL 还是字段根本不存在。

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

先确认 Redis 是否支持字段级过期

字段级过期不是 Redis 早期 Hash 的通用能力。官方命令文档把 HEXPIRE、HPEXPIRE、HTTL、HPTTL 和 HPERSIST 标为 Redis Open Source 7.4.0 起可用。先在实际连接的实例上查看版本，不要只看客户端依赖版本。

# 查看实际服务端版本，避免把客户端版本当成 Redis 版本
redis-cli INFO server | grep '^redis_version:'

# 检查命令是否已注册；低版本通常会返回 unknown command
redis-cli COMMAND INFO HEXPIRE HTTL

如果服务端低于 7.4，EXPIRE 仍只能让整个 Hash 一起过期。此时应把需要独立生命周期的数据拆成多个 key，或升级并评估客户端支持，不要把字段 TTL 误写成普通 Hash 的已有能力。

旧写法为什么会让所有字段一起消失

下面这组命令能给 Hash 设置 key 级 TTL，但它无法表达“profile 保留一天、login_token 只保留五分钟”。key 的 TTL 到期后，整个 Hash 被删除，剩余字段也会一起消失。

# 旧模型：EXPIRE 绑定整个 user:42 Hash，而不是某一个字段
redis-cli HSET user:42 profile "A" login_token "B"
redis-cli EXPIRE user:42 86400

# 查看的是 key 的 TTL，不是 Hash 字段的 TTL
redis-cli TTL user:42

不要用“定期读取 Hash 再手动 HDEL”模拟过期：它会引入轮询延迟、重复清理和多实例竞态。能升级到 Redis 7.4 时，优先使用原生命令；不能升级时再重新设计 key 边界。

用 HEXPIRE 给指定字段配置独立 TTL

正确顺序是先写入字段，再设置过期时间。FIELDS 后的第一个数字必须等于后面字段名的数量。下面让登录令牌五分钟后过期，同时保留用户资料。

# 先创建两个字段；HEXPIRE 只能作用于已经存在的字段
redis-cli HSET user:42 profile "A" login_token "B"

# 只给 login_token 设置 300 秒字段级 TTL
redis-cli HEXPIRE user:42 300 FIELDS 1 login_token

# 同一个 Hash 中 profile 没有字段 TTL，仍可继续读取
redis-cli HGETALL user:42

需要毫秒粒度时改用 HPEXPIRE user:42 300000 FIELDS 1 login_token。如果是固定的绝对时间点，可用 HEXPIREAT；不要把 Unix 时间戳误传给相对 TTL 命令。

重复执行 HEXPIRE 会更新已有 TTL。需要“只在没有 TTL 时设置”用 NX，只更新已有 TTL 用 XX；GT 和 LT 可限制新过期时间只能变长或变短。

用 TTL 返回值判断配置到底卡在哪里

字段级命令对每个字段返回一个状态码，顺序与请求字段一致。排查时不要只看客户端是否没有抛异常，先把数组逐项记录下来。

# 秒级检查字段 TTL；返回数组与字段顺序一一对应
redis-cli HTTL user:42 FIELDS 2 profile login_token

# 需要更细粒度的剩余时间时使用毫秒
redis-cli HPTTL user:42 FIELDS 2 profile login_token

# 取消字段过期，让 login_token 变成持久字段
redis-cli HPERSIST user:42 FIELDS 1 login_token

例如结果为 -1，说明字段还在，只是没有字段级 TTL；结果为 -2，则应先回到写入路径排查。若客户端把负数转换成异常对象，也要保留原始数组，避免丢失定位信息。

兼容性和覆写陷阱要单独检查

HSET 覆写字段值会清除该字段原有 TTL，这是“刚设置就不再过期”最常见的原因之一。更新流程应选择“写入后再次 HEXPIRE”，或在支持 Redis 8.0 的环境评估带过期参数的 HSETEX。同时确认 Go、Java、Python 等客户端版本已经封装这些新命令；否则可以先用客户端的通用命令执行接口发送原始命令。

生产排查可以按这个顺序：服务端版本 → key 类型 → 字段存在性 → FIELDS 数量 → 设置返回码 → HTTL/HPTTL → 后续是否被 HSET 覆写。这个顺序能把“命令不支持”和“TTL 被业务代码清掉”分开。

采用建议：把字段生命周期写进更新流程

适合字段级过期的场景是一个实体中不同字段的保留时间确实不同，例如用户资料长期存在、登录令牌短期存在。把 TTL 设置封装在同一次业务更新中，并在测试中覆盖“成功设置、字段不存在、覆写后续期、HPERSIST 取消”四条路径。若字段数量很多，还要结合访问模式评估 Hash 维护成本。

常见问题

为什么对 Hash 执行 EXPIRE 后，某个字段不能单独续期？

因为 EXPIRE 绑定的是整个 key。要单独续期必须使用 Redis 7.4 起的 HEXPIRE 或 HPEXPIRE。

HTTL 返回 -1 是不是字段已经过期？

不是。-1 表示字段存在但没有关联的过期时间；字段不存在通常返回 -2。

设置 HEXPIRE 后再次 HSET，为什么 TTL 消失了？

HSET 覆写字段会清除该字段 TTL。把续期命令放在覆写之后，或评估支持过期参数的 HSETEX。