Redis HTTL 命令详细教程HTTL查询 Hash 中一个或多个字段的剩余生存时间以秒为单位返回。它从 Redis 7.4.0 起提供是字段级过期机制的配套查询命令。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法HTTL key FIELDS numfields field [field ...]项目说明数据类型Hash 的字段级过期时间支持版本Redis 7.4.0 起key一个 Hash KeyFIELDS必填关键字不可省略numfields字段数量必须与后续字段参数个数一致field至少一个字段名不支持通配符返回值数组元素顺序与输入字段顺序一致时间复杂度O(N)N 为指定字段数量ACLread、hash、fast命令标记readonly、fast官方描述指出该命令提供内省能力用于检查某个 Hash 字段还会在 Hash 中保留多少秒毫秒精度版本见 HPTTL。$TRAE_REF二、返回值含义数值含义-2该字段不存在或整个 Key 不存在-1该字段存在但没有设置过期时间永久字段非负整数剩余生存时间单位秒官方示例完整展示了三种结果field1 设置了 300 秒 TTL、field2 无 TTL、field3 不存在查询返回283、-1、-2。$TRAE_REF-1与-2的区别至关重要-1表示字段永久有效-2表示字段根本不存在。业务代码若把两者都当作“没有 TTL”就会把永久字段误判为缺失。三、基础示例以下命令需要 Redis 7.4 或更新版本在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。示例沿用官方示例的结构。HTTL tutorial:{httl}:missing FIELDS 3 field1 field2 field3 DEL tutorial:{httl}:mykey HSET tutorial:{httl}:mykey field1 hello field2 world HEXPIRE tutorial:{httl}:mykey 300 FIELDS 2 field1 field3 HTTL tutorial:{httl}:mykey FIELDS 3 field1 field2 field3预期结果第一条对不存在的 Key 返回(nil)即空值而非数组。HEXPIRE 返回[1, -2]field1 设置成功field3 因不存在返回 -2。最后一条返回形如[283, -1, -2]field1 是剩余秒数field2 永久有效field3 不存在。注意 Key 不存在与字段不存在时的返回形态不同前者是空值后者是数组中的 -2。四、字段 TTL 与 Key TTL 的区别HTTL 只反映字段级过期时间与整个 Key 的过期时间是两套独立机制。命令作用对象单位语义TTL整个 Key秒剩余生存时间PTTL整个 Key毫秒剩余生存时间HTTLHash 字段秒剩余生存时间HPTTLHash 字段毫秒剩余生存时间EXPIRETIME整个 Key秒绝对到期时刻HEXPIRETIMEHash 字段秒绝对到期时刻DEL tutorial:{httl}:two HSET tutorial:{httl}:two a 1 EXPIRE tutorial:{httl}:two 600 HEXPIRE tutorial:{httl}:two 300 FIELDS 1 a TTL tutorial:{httl}:two HTTL tutorial:{httl}:two FIELDS 1 a预期结果TTL 约为 600HTTL 约为 300两者独立存在。谁先到期谁就先限制数据可用性如果字段 TTL 先到字段消失但 Key 仍在如果 Key TTL 先到整个 Hash 都不可见。让字段永久有效用 HPERSIST让整个 Key 永久有效用 PERSIST。五、边界情况与错误处理场景行为Key 不存在返回空值Nil不是数组字段不存在该项返回 -2字段无 TTL该项返回 -1字段有 TTL该项返回剩余秒数随时间递减Key 是 String、List 等非 Hash报 WRONGTYPE 错误numfields 与实际字段数不符报语法错误未写 FIELDS 关键字报语法错误HTTL 不会刷新字段或 Key 的 TTL。读取操作本身不影响生命周期字段不会因为被查询而延长存活时间。六、哪些操作会改变字段 TTL理解 HTTL 数值变化的来源有助于排查异常。操作对字段 TTL 的影响HSET 覆盖该字段清除该字段的 TTLHDEL 删除该字段字段与 TTL 一并消失HINCRBY、HINCRBYFLOAT保留 TTL在原值上运算不覆盖HEXPIRE 系列设置或更新 TTLHPERSIST移除 TTL字段转为永久字段到期字段被自动移除之后查询返回 -2其中“HSET 覆盖会清除 TTL”是最常见的意外来源业务先设置 TTL随后又用 HSET 更新了同一个字段TTL 就消失了。需要写入新值并保留期限时可使用 HSETEX 的 KEEPTTL 选项Redis 8.0 起。七、Python 客户端示例前提为已安装 redis-py 且服务端为 Redis 7.4 或更新版本。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)ktutorial:{httl}:pythontry:r.delete(k)r.hset(k,mapping{a:A,b:B})r.execute_command(HEXPIRE,k,300,FIELDS,1,a)fields[a,b,missing]rawr.execute_command(HTTL,k,FIELDS,len(fields),*fields)print(raw)# 形如 [299, -1, -2]forname,valueinzip(fields,raw):ifvalue-2:print(name,不存在)elifvalue-1:print(name,永久有效)else:print(name,剩余秒数,value)print(r.execute_command(HTTL,tutorial:{httl}:missing,FIELDS,1,a))# None整个 Key 不存在时返回空值finally:r.delete(k)r.close()八、并发、原子性与典型场景单条 HTTL 是原子的返回执行瞬间的快照。但“先 HTTL 判断是否临近过期再决定续期”是跨命令流程两次调用之间字段可能已到期或被其他客户端续期。需要原子条件续期时可使用 HGETEXRedis 8.0 起或 Lua 脚本。典型用途监控字段剩余寿命、核对缓存续期是否符合预期、排查字段为何提前消失、在业务中判断“即将过期则主动刷新”。由于是只读且复杂度只与查询字段数相关可以安全地用于线上排障。九、练习、排错与总结练习新建tutorial:{httl}:exercise写入 a1、b2查询两个字段预期[-1, -1]用HEXPIRE ... 300 FIELDS 1 a设置 TTL 后查询预期 a 为接近 300 的秒数、b 为 -1执行HSET ... a 99后再次查询预期 a 变为 -1理解覆盖会清除 TTL最后查询不存在的字段名预期为 -2。排错要点返回 -1 表示字段永久有效而非缺失返回 -2 表示字段或 Key 不存在整个 Key 缺失时返回空值而非数组TTL 意外消失时检查是否用 HSET 覆盖过该字段unknown command 时检查服务端版本不低于 7.4。清理使用DEL tutorial:{httl}:missing tutorial:{httl}:mykey tutorial:{httl}:two tutorial:{httl}:exercise。速记7.4 起支持、只读、秒级剩余时间、FIELDS 必填、-1 永久、-2 不存在、HSET 覆盖会清除字段 TTL。