Redis HTTL 命令详细教程
HTTL 查询 Hash 中一个或多个字段的剩余生存时间，以秒为单位返回。它从 Redis 7.4.0 起提供，是字段级过期机制的配套查询命令。
资料合集：https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338
一、概览与语法
redis
HTTL 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 |
官方描述指出，该命令提供内省能力，用于检查某个 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 运行。示例沿用官方示例的结构。
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 | 毫秒 | 剩余生存时间 |
| HTTL | Hash 字段 | 秒 | 剩余生存时间 |
| HPTTL | Hash 字段 | 毫秒 | 剩余生存时间 |
| EXPIRETIME | 整个 Key | 秒 | 绝对到期时刻 |
| HEXPIRETIME | Hash 字段 | 秒 | 绝对到期时刻 |
redis
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 约为 600，HTTL 约为 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 覆盖该字段 | 清除该字段的 TTL |
| HDEL 删除该字段 | 字段与 TTL 一并消失 |
| HINCRBY、HINCRBYFLOAT | 保留 TTL（在原值上运算，不覆盖） |
| HEXPIRE 系列 | 设置或更新 TTL |
| HPERSIST | 移除 TTL，字段转为永久 |
| 字段到期 | 字段被自动移除，之后查询返回 -2 |
其中"HSET 覆盖会清除 TTL"是最常见的意外来源：业务先设置 TTL，随后又用 HSET 更新了同一个字段，TTL 就消失了。需要写入新值并保留期限时，可使用 HSETEX 的 KEEPTTL 选项（Redis 8.0 起）。
七、Python 客户端示例
前提为已安装 redis-py 且服务端为 Redis 7.4 或更新版本。
python
import redis
r = redis.Redis(host="localhost", port=6379, decode_responses=True)
k = "tutorial:{httl}:python"
try:
r.delete(k)
r.hset(k, mapping={"a": "A", "b": "B"})
r.execute_command("HEXPIRE", k, 300, "FIELDS", 1, "a")
fields = ["a", "b", "missing"]
raw = r.execute_command("HTTL", k, "FIELDS", len(fields), *fields)
print(raw) # 形如 [299, -1, -2]
for name, value in zip(fields, raw):
if value == -2:
print(name, "不存在")
elif value == -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 判断是否临近过期，再决定续期"是跨命令流程，两次调用之间字段可能已到期或被其他客户端续期。需要原子条件续期时，可使用 HGETEX（Redis 8.0 起）或 Lua 脚本。
典型用途：监控字段剩余寿命、核对缓存续期是否符合预期、排查字段为何提前消失、在业务中判断"即将过期则主动刷新"。由于是只读且复杂度只与查询字段数相关，可以安全地用于线上排障。
九、练习、排错与总结
练习：新建 tutorial:{httl}:exercise，写入 a=1、b=2；查询两个字段，预期 [-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。