Redis HPTTL 命令详细教程HPTTL查询 Hash 中一个或多个字段的剩余生存时间以毫秒为单位返回。它是只读命令不修改任何数据或期限。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法HPTTL key FIELDS numfields field [field ...]项目说明数据类型Hash 的字段级过期时间支持版本Redis 7.4.0 起key一个 Hash KeyFIELDS必填关键字不可省略numfields字段数量必须与后续字段参数个数一致field至少一个字段名不支持通配符返回值数组元素顺序与输入字段顺序一致时间复杂度O(N)N 为指定字段数量ACLread、hash、fast命令标记readonly、fast官方说明与 HTTL 相同返回设置了过期时间的字段的剩余 TTL但单位是毫秒而非秒。$TRAE_REF二、返回值含义数值含义-2该字段不存在或整个 Key 不存在-1该字段存在但没有设置过期时间永久字段非负整数剩余生存时间单位毫秒官方示例清楚展示了三种结果的并存对 field1 设置了 300 秒 TTLfield2 无 TTLfield3 不存在查询返回292202、-1、-2三个值。$TRAE_REF-1与-2的区别是关键-1表示字段永久有效-2表示字段根本不存在。把两者混为一谈会导致“把永久字段当成缺失字段重新写入”这类逻辑错误。三、基础示例以下命令需要 Redis 7.4 或更新版本在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。官方示例还演示了不存在的 Key 的返回形态。HPTTL tutorial:{hpttl}:missing FIELDS 3 field1 field2 field3 DEL tutorial:{hpttl}:mykey HSET tutorial:{hpttl}:mykey field1 hello field2 world HEXPIRE tutorial:{hpttl}:mykey 300 FIELDS 2 field1 field3 HPTTL tutorial:{hpttl}:mykey FIELDS 3 field1 field2 field3预期结果第一条对不存在的 Key 返回(nil)即空值而非数组。HEXPIRE 返回[1, -2]field1 设置成功field3 因不存在返回 -2。最后一条返回形如[292202, -1, -2]field1 是毫秒剩余时间field2 无 TTLfield3 不存在。注意 Key 不存在时的返回与字段不存在时不同整个 Key 缺失时返回空值Key 存在但字段缺失时返回数组中对应位置的 -2。这一点与 HTTL 一致容易在客户端处理时被忽略。四、HTTL 与 HPTTL 的对照命令单位返回剩余时间适用场景HTTL秒是人工排查、秒级精度足够HPTTL毫秒是亚秒级 TTL、精度核对HEXPIRETIME秒否返回绝对时刻需要知道具体到期时间点HPEXPIRETIME毫秒否返回绝对时刻毫秒级绝对到期时刻HPTTL 的数值随时间递减每次调用都可能得到不同结果HPEXPIRETIME 在期限内保持稳定。需要判断“还能活多久”用 HPTTL需要判断“什么时候到期”用 HPEXPIRETIME。五、字段 TTL 与 Key TTL 的区别HPTTL 只查询字段级 TTL与整个 Key 的 TTL 是两套独立机制。命令作用对象单位TTL / PTTL整个 Key秒 / 毫秒HTTL / HPTTLHash 字段秒 / 毫秒DEL tutorial:{hpttl}:two HSET tutorial:{hpttl}:two a 1 EXPIRE tutorial:{hpttl}:two 600 HPEXPIRE tutorial:{hpttl}:two 300000 FIELDS 1 a TTL tutorial:{hpttl}:two HPTTL tutorial:{hpttl}:two FIELDS 1 a预期结果TTL 约为 600HPTTL 约为 300000两者独立存在谁先到期谁先限制数据可用性。要让字段永久有效使用 HPERSIST要让整个 Key 永久有效使用 PERSIST。六、边界情况与错误处理场景行为Key 不存在返回空值Nil不是数组字段不存在该项返回 -2字段无 TTL该项返回 -1字段有 TTL该项返回毫秒剩余时间随时间递减Key 是 String、List 等非 Hash报 WRONGTYPE 错误numfields 与实际字段数不符报语法错误未写 FIELDS 关键字报语法错误HPTTL 不会刷新字段或 Key 的 TTL。读取本身不影响生命周期这与访问时间LRU统计是两回事。七、Python 客户端示例前提为已安装 redis-py 且服务端为 Redis 7.4 或更新版本。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)ktutorial:{hpttl}:pythontry:r.delete(k)r.hset(k,mapping{a:A,b:B})r.execute_command(HPEXPIRE,k,300000,FIELDS,1,a)fields[a,b,missing]rawr.execute_command(HPTTL,k,FIELDS,len(fields),*fields)print(raw)# 形如 [299847, -1, -2]forname,valueinzip(fields,raw):ifvalue-2:print(name,不存在)elifvalue-1:print(name,永久有效)else:print(name,剩余毫秒,value)print(r.execute_command(HPTTL,tutorial:{hpttl}:missing,FIELDS,1,a))# None整个 Key 不存在时返回空值finally:r.delete(k)r.close()八、并发、原子性与典型场景单条 HPTTL 是原子的返回执行瞬间的快照。但“先 HPTTL 判断是否临近过期再决定续期”是跨命令流程两次调用之间字段可能已到期或被其他客户端续期。需要原子条件续期时可使用 HGETEXRedis 8.0 起或 Lua 脚本。典型用途监控字段剩余寿命、核对续期逻辑是否符合预期、在业务中判断“即将过期则主动刷新”、排查字段为何提前消失。由于是只读且复杂度只与查询字段数相关可以安全地用于线上排障。九、练习、排错与总结练习新建tutorial:{hpttl}:exercise写入 a1、b2查询两个字段预期[-1, -1]用HPEXPIRE ... 300000 FIELDS 1 a设置 TTL 后再次查询预期 a 为接近 300000 的毫秒值、b 为 -1执行HPERSIST ... FIELDS 1 a后查询预期 a 回到 -1最后查询一个不存在的字段名预期为 -2。排错要点返回 -1 表示字段永久有效而非缺失返回 -2 表示字段或 Key 不存在整个 Key 缺失时返回空值而非数组客户端需单独处理数值只有三位数说明用的是秒级 HTTL应确认命令选择unknown command 时检查服务端版本不低于 7.4。清理使用DEL tutorial:{hpttl}:missing tutorial:{hpttl}:mykey tutorial:{hpttl}:two tutorial:{hpttl}:exercise。速记7.4 起支持、只读、毫秒剩余时间、FIELDS 必填、-1 永久、-2 不存在、Key 缺失返回空值。