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 Key |
| FIELDS | 必填关键字，不可省略 |
| numfields | 字段数量，必须与后续字段参数个数一致 |
| field | 至少一个字段名；不支持通配符 |
| 返回值 | 数组，元素顺序与输入字段顺序一致 |
| 时间复杂度 | O(N)，N 为指定字段数量 |
| ACL | @read、@hash、@fast |
| 命令标记 | readonly、fast |
官方说明：与 HTTL 相同，返回设置了过期时间的字段的剩余 TTL，但单位是毫秒而非秒。$TRAE_REF
二、返回值含义
| 数值 | 含义 |
|---|---|
| -2 | 该字段不存在，或整个 Key 不存在 |
| -1 | 该字段存在，但没有设置过期时间（永久字段） |
| 非负整数 | 剩余生存时间，单位毫秒 |
官方示例清楚展示了三种结果的并存：对 field1 设置了 300 秒 TTL，field2 无 TTL，field3 不存在，查询返回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 无 TTL，field3 不存在。
注意 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 / HPTTL | Hash 字段 | 秒 / 毫秒 |
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 约为 600，HPTTL 约为 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 r=redis.Redis(host="localhost",port=6379,decode_responses=True)k="tutorial:{hpttl}:python"try:r.delete(k)r.hset(k,mapping={"a":"A","b":"B"})r.execute_command("HPEXPIRE",k,300000,"FIELDS",1,"a")fields=["a","b","missing"]raw=r.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 判断是否临近过期，再决定续期”是跨命令流程，两次调用之间字段可能已到期或被其他客户端续期。需要原子条件续期时，可使用 HGETEX（Redis 8.0 起）或 Lua 脚本。
典型用途：监控字段剩余寿命、核对续期逻辑是否符合预期、在业务中判断“即将过期则主动刷新”、排查字段为何提前消失。由于是只读且复杂度只与查询字段数相关，可以安全地用于线上排障。
九、练习、排错与总结
练习：新建tutorial:{hpttl}:exercise，写入 a=1、b=2；查询两个字段，预期[-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 缺失返回空值。