Redis Hash 字段过期怎么验收：HEXPIRE、HPTTL 与惰性删除边界

给用户会话缓存加过期时间时，整条 Redis Hash 能设置 TTL，但 Hash 里的某一个字段以前很难单独控制。现在使用 HEXPIRE 可以让 profile:10086 里的 session_token 和 last_seen 拥有不同的生命周期。不过，字段过期不是“时间一到整条 key 立刻删除”：读写路径、惰性清理、条件参数和整 key TTL 都会影响验收结果。

字段级过期的验收不能只校验 key 是否存在，要把字段返回值、字段级剩余时间、Hash 总长度、整 key 剩余TTL四个维度都覆盖到，才能避免把惰性清理的延迟误差当成功能异常。

先还原现场：字段过期了，为什么 Hash 还在

假设用户缓存写在 profile:10086：

redis-cli HSET profile:10086 session_token abc123 last_seen 2026-08-09T06:20:00+08:00
redis-cli HEXPIRE profile:10086 300 FIELDS 1 session_token
redis-cli HLEN profile:10086
redis-cli HGETALL profile:10086

五分钟后，session_token 可能已经不可读，但 last_seen 仍然存在，所以 EXISTS profile:10086 继续返回 1。这个结果不是过期失效，而是字段级生命周期正在发挥作用。排查时先看字段，不要只盯着 key 的存在性。

用 HTTL 和 HPTTL 读懂三个返回值

秒级检查可以使用 HTTL，需要更细的窗口时使用 HPTTL：

redis-cli HTTL profile:10086 FIELDS 2 session_token last_seen
redis-cli HPTTL profile:10086 FIELDS 2 session_token last_seen

典型结果可以按下面的方式理解：

HPTTL 的结果是毫秒级剩余时间，适合短会话、验证码或刷新窗口。它不是“绝对精确到业务时刻”的承诺，因为网络往返、命令排队和检查发生在不同时间点。验收时可以允许几十毫秒级的测试误差，但不能把 -1 和 -2 混为一谈。

条件参数是最容易漏掉的写入边界

生产代码常常需要“只有已有 TTL 时才延长”或“只为没有 TTL 的字段补一次过期时间”。这时要用条件参数，不能用无条件写法覆盖掉原策略。

# 只有字段已有过期时间时才增加 60 秒
redis-cli HEXPIRE profile:10086 60 GT FIELDS 1 session_token

# 只有字段没有 TTL 时才设置 300 秒
redis-cli HEXPIRE profile:10086 300 NX FIELDS 1 session_token

NX、XX 控制字段是否已有 TTL，GT、LT 比较新旧过期时间。比如刷新登录态时，业务可能只允许延长生命周期，不允许一次异常请求把 TTL 缩短；这就应该明确使用 GT，并记录命令返回的逐字段结果。

这里别急着把返回 0 当成 Redis 故障。条件不满足、字段不存在、传入字段数量不一致，都可能让某个字段没有按预期改变。应用层应该把目标字段、条件、返回数组和最终 HPTTL 一起打到调试日志里。

字段过期与整 key 过期不要混成一套策略

一个 Hash 可以同时拥有字段级 TTL 和 key 级 TTL。比如：

redis-cli EXPIRE profile:10086 86400
redis-cli HEXPIRE profile:10086 300 FIELDS 1 session_token
redis-cli TTL profile:10086
redis-cli HPTTL profile:10086 FIELDS 1 session_token

字段级 TTL 先到时，session_token 不再返回；key 级 TTL 到时，整个 Hash 被删除，剩余字段也一起消失。缓存设计要先回答“字段之间是否允许独立存活”：如果答案是否定的，单独使用 Hash 字段过期反而增加了验收复杂度；如果答案是肯定的，字段级 TTL 能避免为了一个短期字段频繁重建整条 key。

一轮可重复验收：从写入到不可见

测试字段过期时，建议使用一个专用 key，避免旧数据影响结果：

1. 用 HSET 写入两个字段，记录 HLEN 和 HGETALL 初始结果。
2. 用 HEXPIRE 只给短生命周期字段设置 TTL，并立即用 HPTTL 核对大于 0。
3. 等待超过 TTL 后分别执行 HGET、HEXISTS、HLEN，确认目标字段不可见、长生命周期字段仍在。
4. 再次查询 EXISTS 与 TTL，确认整 key 是否因为最后一个字段消失而被清理。

redis-cli DEL profile:test:expiry
redis-cli HSET profile:test:expiry short x long y
redis-cli HEXPIRE profile:test:expiry 2 FIELDS 1 short
redis-cli HPTTL profile:test:expiry FIELDS 2 short long
sleep 3
redis-cli HGET profile:test:expiry short
redis-cli HGET profile:test:expiry long
redis-cli HLEN profile:test:expiry

如果测试环境与线上 Redis 版本不同，先核对命令是否存在，再把“字段不存在”和“字段无 TTL”的返回值写进自动化断言。只断言 EXISTS 很容易漏掉字段级过期已经生效但整 key 仍存在的情况。

常见问题与边界判断

Hash 只剩一个字段时，字段过期会自动删除整条 key 吗？

当最后一个字段过期并被清理后，Hash 没有内容，整条 key 通常也会变得不可见；验收仍应分别检查字段和 key，不要把清理时机写成业务实时事件。

为什么 HPTTL 返回 -1？

通常表示字段存在但没有字段级 TTL。检查是否只执行了 HSET、条件参数是否未命中，以及应用是否把整 key 的 EXPIRE 误当成字段 TTL。

HEXPIRE 设置成功后能保证字段马上消失吗？

不能把过期时间理解成定时回调。Redis 会在访问、主动周期清理等时机处理过期字段，业务可见性应以读取结果为准。

什么时候更适合给整条 Hash 设置 EXPIRE？

当所有字段应该同时失效、数据量不大且生命周期一致时，整 key TTL 更容易理解和运维；只有字段确实需要独立存活时，再采用 HEXPIRE。

把字段过期纳入缓存验收清单

Redis Hash 字段过期真正难的地方，不是记住 HEXPIRE 的命令格式，而是区分字段状态、整 key 状态和条件写入结果。先用 HTTL 或 HPTTL 验证 TTL 是否写入，再用读取结果确认字段何时不可见，最后检查 Hash 长度和整 key TTL。对刷新型缓存明确 NX、GT 等条件，对同一 key 的字段生命周期做记录，这样字段过期就能从“偶尔读到空值”变成可复查的缓存行为。