Redis HTTL 怎样查询 hash 字段剩余时间

如果一个 Redis hash 里同时放着登录会话、短期配额和长期资料，给整个 key 设置一个统一过期时间往往不够：会话可能 30 分钟失效，配额需要 1 小时，而昵称应该一直保留。Redis 7.4 及以上支持 hash 字段级过期，这时可以用 HTTL 查询指定字段还剩多少秒。

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

最小可用写法是 HTTL profile:1001 FIELDS 3 session_token quota nickname。返回数组按字段请求顺序对应：正数表示剩余秒数，-1 表示字段存在但没有过期时间，-2 表示字段或整个 hash 不存在；需要毫秒精度时改用 HPTTL。

先判断字段级过期是不是正确的模型

HTTL 解决的是“一个 hash 内不同字段有不同生命周期”的查询问题。它不是普通 TTL key 的替代别名，也不会为没有过期时间的字段推算出一个时间。字段过期能力从 Redis Open Source 7.4.0 开始提供，设置通常由 HEXPIRE 或 HPEXPIRE 完成，读取则分别使用秒级的 HTTL 和毫秒级的 HPTTL。

因此，先把需求分成三类：如果整个对象应该一起失效，继续用 key 级过期；如果对象中的字段要独立回收，再使用字段级过期；如果调用方只关心某个绝对时间点，则可以配合 HEXPIRETIME 读取 Unix 时间戳。这里的文章主线只保留第三种方案中的剩余时间查询。

# 先写入一个包含三种生命周期的 hash；字段名按业务替换
redis-cli HSET profile:1001 session_token "token-value" quota "20" nickname "小林"

# 给会话和配额设置字段级 TTL；FIELDS 后的数字必须等于字段数量
redis-cli HEXPIRE profile:1001 1800 FIELDS 1 session_token
redis-cli HEXPIRE profile:1001 3600 FIELDS 1 quota

用 HTTL 按字段顺序读取剩余秒数

HTTL 的语法是 HTTL key FIELDS numfields field [field ...]。numfields 不是一个可省略的装饰参数，而是后面字段名的数量；批量查询时，Redis 会返回一个与请求字段一一对应的数组。把字段名和返回值按同一顺序配对，是应用侧最重要的处理规则。

# 一次查询三个字段；返回值按 session_token、quota、nickname 顺序排列
redis-cli HTTL profile:1001 FIELDS 3 session_token quota nickname

# 只查询需要展示倒计时的字段，减少不必要的返回项
redis-cli HTTL profile:1001 FIELDS 2 session_token quota

在静态示意中，若会话还剩约 1790 秒、配额还剩约 3590 秒、昵称没有设置过期时间，结果可以理解为 [1790, 3590, -1]。剩余秒数会随着时间减少，所以不要把一次读取的数字当成长期缓存的事实；如果页面要展示倒计时，应在自己的响应中记录查询时刻，并接受网络传输和取整带来的小幅误差。

把 -1、-2 和正数当成三种业务状态

HTTL 的返回值不能只用“是否大于 0”粗略判断。官方返回信息把每个字段的结果分成三类：正整数是剩余秒数；-1 是字段存在但没有关联的过期时间；-2 是字段不存在，或者保存该字段的 key 不存在。

# 同时询问有 TTL、无 TTL 和不存在的字段
redis-cli HTTL profile:1001 FIELDS 3 session_token nickname missing_field

# 结果解释：正数走倒计时，-1 走“长期字段”，-2 走缺失或已回收分支
# 这里的数组位置必须与上面的字段顺序保持一致

-1 不应该自动被当成错误。比如昵称是长期资料，它没有字段级过期是正常状态；相反，登录会话若返回 -1，可能意味着写入流程忘记设置过期时间，需要按业务规则告警。-2 也要区分“用户主动删除”和“会话已自然过期”，必要时结合业务状态字段或事件记录判断原因。

批量查询的好处是一次请求可以得到一组字段的生命周期快照，但它不是事务性业务判断。应用读取之后，字段仍可能在下一毫秒过期；如果后续动作要求强一致的存在性判断，就应把真正的写入或删除条件放到合适的 Redis 命令中，而不是依赖 HTTL 的旧结果。

按精度和负载选择 HTTL 或 HPTTL

HTTL 的单位是秒，适合会话巡检、批量清理、运营后台和分钟级告警。它的复杂度是按请求字段数线性增长，因此一条命令查询几十个字段时，成本主要取决于字段数量，而不是把整个 hash 读出来再由应用计算。

如果任务需要毫秒级调度，例如短暂租约、延迟重试或防抖窗口，应使用 HPTTL。它与 HTTL 的状态含义相同，但正数单位改为毫秒。不要把 HPTTL 的数值直接当成秒，也不要用频繁轮询去弥补错误的时间单位。

# 秒级查询：适合普通会话和批量巡检
redis-cli HTTL profile:1001 FIELDS 2 session_token quota

# 毫秒级查询：适合需要更细时间粒度的短窗口
redis-cli HPTTL profile:1001 FIELDS 2 session_token quota

# 绝对时间查询：需要 Unix 时间戳时使用对应的 HEXPIRETIME 命令
redis-cli HEXPIRETIME profile:1001 FIELDS 1 session_token

在云上或高并发环境中，查询策略还要考虑调用频率：页面每次刷新都读取所有字段，通常不如后端按需查询；监控任务可以固定字段集合并控制轮询间隔；清理任务则应按分片或业务租户拆分，避免一次请求带上超大的字段列表。HTTL 负责观察，不负责批量删除。

把查询结果接到清理、刷新和监控闭环

一个可维护的做法是让查询结果只承担“状态判断”，把动作分开：正数进入倒计时或续期判断，-1 进入长期字段路径，-2 进入缺失处理。要刷新过期时间时使用 HEXPIRE，要清除字段过期则使用 HPERSIST，不要通过反复读取 HTTL 来模拟续期。

# 只有业务确认仍需续期时才刷新 TTL，避免无条件延长会话
redis-cli HEXPIRE profile:1001 1800 XX FIELDS 1 session_token

# 取消某个字段的过期，让它恢复为持久字段
redis-cli HPERSIST profile:1001 FIELDS 1 nickname

# 清理整个 hash 前先确认这是业务允许的对象级动作
redis-cli DEL profile:1001

监控上建议至少记录字段级状态数量：剩余时间低于阈值的字段数、返回 -1 的字段数、返回 -2 的字段数，以及查询错误率。这样既能发现会话即将过期，也能发现写入链路意外漏设 TTL。对于会话类数据，还要把“续期”和“访问”分开设计，避免一次只读查询悄悄改变生命周期。

常见问题

HTTL 能查询整个 hash 的统一过期时间吗？

不能。HTTL 针对指定字段返回字段级 TTL；整个 key 的过期时间仍应使用 key 级 TTL 命令，并且两种生命周期不能混为一个数。

为什么字段明明存在，HTTL 却返回 -1？

这表示字段存在但没有关联的过期时间。它可能是设计如此，也可能是写入流程没有调用 HEXPIRE，需要结合字段职责判断是否应该告警。

HTTL 返回 -2 一定表示 Redis 出错吗？

不是。-2 表示请求的字段不存在，或者整个 hash key 不存在。字段自然过期、主动删除和键被清理都可能导致这个结果。

需要毫秒级结果时能不能把 HTTL 乘以 1000？

不建议。HTTL 已经按秒取整，乘以 1000 会放大误差；需要毫秒级语义时直接使用 HPTTL。

小结

Redis HTTL 的正确用法可以归纳为四步：先确认 Redis 版本和字段级过期模型，再用 FIELDS 按需查询，按字段顺序解释正数、-1 和 -2，最后根据精度和负载选择 HTTL 或 HPTTL，并把结果接入续期、清理和监控。这样查询到的就不只是一个倒计时数字，而是能支撑生命周期决策的状态信息。