Redis Hash field 过期后 HGETALL 返回什么

Redis Hash 的 field 过期后，HGETALL 不会返回一个“已过期”的占位项：Redis 会把到期 field 从 Hash 中删除，命令只返回仍然存在的 field 和 value。比如 session 先到期而 profile 还在，结果里只剩 profile；如果最后一个 field 也到期，HGETALL 返回空结果，整个 Hash key 也就没有可读内容了。

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

先区分 Hash key 过期和 field 过期

传统的 EXPIRE user:100 60 是给整个 Hash key 设 60 秒生命周期；时间到后，所有 field 一起不可见。Redis 7.4 新增的 HEXPIRE 则把过期时间挂在指定 field 上，因此同一个 Hash 可以让短期 session 和长期 profile 使用不同 TTL。

这个差别决定了 HGETALL 的返回：只要还有未过期 field，它就返回这些 field-value 对；不是返回空值来表示某个 field 已过期。field 过期本质上是删除动作，Hash 只剩空集合时，业务上应按“没有数据”处理。

用 HEXPIRE 设置单个 field 的 TTL

下面的示例让 session 五秒后过期，profile 保持持久。命令中的 FIELDS 1 session 表示后面只列出一个 field；可以一次指定多个 field，但每个 field 都会得到同一个秒级 TTL。

# 先写入两个字段，便于观察一个过期、一个保留
HSET user:100 session "token-a" profile "basic"

# 只给 session 设置 5 秒 TTL，不影响 profile
HEXPIRE user:100 5 FIELDS 1 session

# 查看当前 Hash 的全部可见字段
HGETALL user:100

如果 HEXPIRE 返回数组中的值是 1，表示该字段的过期时间已设置或更新；-2 表示指定 field 不存在。需要毫秒精度时可改用 HPEXPIRE。这些命令只在支持 field expiration 的 Redis 版本上可用，旧实例应先确认版本和部署兼容性。

观察 HGETALL 在字段到期前后的结果

设置成功后，立即读取可能看到两个字段：

1) "session"
2) "token-a"
3) "profile"
4) "basic"

等待 session 到期，再执行 HGETALL user:100，预期只剩下 profile 和 basic。如果 profile 也设置了 TTL 并随后到期，返回就是空数组，而不是包含空字符串的键值对。此时用 HLEN user:100 得到 0，应用层应把它当作 Hash 不存在或已无有效记录。

不要把“刚过期但仍在网络往返中”理解成 Redis 返回不稳定。过期判断发生在命令处理时，测试脚本若把睡眠时间写得刚好等于 TTL，就可能在边界附近看到前后两种合法结果；生产逻辑应根据返回集合和 TTL 再决定是否重建字段。

用 HTTL 排查重新写入和边界时刻

想确认 field 是否仍有过期时间，可以直接查询：

# 查询两个字段的剩余秒数；返回 -2 通常表示 field 不存在
HTTL user:100 FIELDS 2 session profile

# 需要更细的时间粒度时查询毫秒 TTL
HPTTL user:100 FIELDS 2 session profile

如果 session 已到期，查询它通常返回表示 field 不存在的 -2；仍存在但没有 TTL 的 profile 会返回 -1。最容易误判的情况是重新执行 HSET user:100 session "token-b"：这是覆盖或重新创建 field 的写操作，会清除原来的 field expiration，之后必须再次执行 HEXPIRE。

相关问题

HGETALL 会刷新 Hash field 的过期时间吗？

不会。它只是读取当前仍存在的 field，不会延长 field TTL；需要续期时显式调用 HEXPIRE 或 HPEXPIRE。

field 过期后整个 Hash key 会马上消失吗？

只有当 Hash 中没有剩余 field 时才会变成空 key；如果还有其他 field，key 继续存在并可被 HGETALL 读取。

为什么 HGETALL 还能读到刚刚写入的字段？

因为 HSET 写入或覆盖 field 后，原 field TTL 会被清除。把写入和设置过期时间作为同一业务操作处理，并用 HTTL 复核。