Redis HPEXPIRE 命令详细教程HPEXPIRE为 Hash 中一个或多个字段设置以毫秒为单位的相对过期时间。它与 HEXPIRE 语义完全相同区别只在时间精度。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、概览与语法HPEXPIRE key milliseconds [NX | XX | GT | LT] FIELDS numfields field [field ...]项目说明数据类型Hash 的字段级过期时间支持版本Redis 7.4.0 起key一个 Hash Keymilliseconds整数毫秒数相对于本次命令执行时刻条件选项NX、XX、GT、LT 四者最多选一互斥FIELDS必填关键字numfields字段数量必须与后续字段参数个数一致时间复杂度O(N)N 为指定字段数量ACLwrite、hash、fast命令标记write、denyoom、fast官方描述直接指出本命令与 HEXPIRE 工作方式相同只是过期时间以毫秒而非秒指定。$TRAE_REF二、逐字段返回值返回数组元素顺序与输入字段顺序一致。数值含义-2该字段不存在或整个 Key 不存在0指定的 NX、XX、GT、LT 条件未满足1过期时间已设置或更新2以 0 毫秒调用时字段被立即删除官方说明中2的触发条件是以 0 秒或 0 毫秒调用 HEXPIRE 或 HPEXPIRE或者以过去的 Unix 时间调用 HEXPIREAT 或 HPEXPIREAT。错误情形包括参数解析失败、缺少必需参数、出现未知参数、参数类型或范围不合法以及 Key 存在但不是 Hash。$TRAE_REF三、基础示例以下命令需要 Redis 7.4 或更新版本在测试实例的 redis-cli 中执行。文中结果是预期说明未实际连接 Redis 运行。DEL tutorial:{hpexpire}:profile HSET tutorial:{hpexpire}:profile name Alice temp draft HPEXPIRE tutorial:{hpexpire}:profile 2000 FIELDS 2 temp name HPTTL tutorial:{hpexpire}:profile FIELDS 2 temp name HPEXPIRE tutorial:{hpexpire}:profile 2000 FIELDS 2 temp absent预期结果HPEXPIRE 返回[1, 1]HPTTL 返回两个接近 2000 的毫秒值最后一次返回[1, -2]absent 因不存在为 -2。手动等待超过 2 秒后再执行HGETALL tutorial:{hpexpire}:profile会得到空数组因为两个字段都到期整个 Key 随之消失。四、与 HEXPIRE 及绝对时间版本的对照命令时间表达单位起始版本HEXPIRE相对秒7.4HPEXPIRE相对毫秒7.4HEXPIREAT绝对秒级时间戳7.4HPEXPIREAT绝对毫秒级时间戳7.4相对时间适合“从现在起多少时间后过期”的场景例如缓存 2 秒内有效、验证码 5 分钟有效。绝对时间适合“在某个固定时刻过期”的场景例如活动在指定时间点结束。相对时间在重试时会重新计时绝对时间不会这一点在设计幂等接口时很重要。毫秒精度并不意味着毫秒级精确定时。Redis 的过期清理是惰性与定期相结合的字段到期与实际不可见之间可能存在很短但非零的延迟不要依赖它做精确调度。五、条件选项 NX、XX、GT、LT四个选项互斥对每个字段独立判断。选项判断条件NX字段当前没有过期时间时才设置XX字段当前已有过期时间时才设置GT新过期时间严格晚于当前过期时间时才设置LT新过期时间严格早于当前过期时间时才设置官方特别说明对于 GT 与 LT 而言没有过期时间的字段non-volatile被视为无限大的 TTL。因此有限时间的 GT 对无 TTL 字段通常不成立而 LT 会成立。$TRAE_REFDEL tutorial:{hpexpire}:cond HSET tutorial:{hpexpire}:cond a A b B HPEXPIRE tutorial:{hpexpire}:cond 1000 XX FIELDS 1 a HPEXPIRE tutorial:{hpexpire}:cond 1000 NX FIELDS 1 a HPEXPIRE tutorial:{hpexpire}:cond 5000 GT FIELDS 2 a b HPEXPIRE tutorial:{hpexpire}:cond 100 LT FIELDS 2 a b在无并发修改的前提下四次调用依次返回[0]、[1]、[1, 0]、[1, 1]。GT 对已有 1000 毫秒期限的 a 成立b 无 TTL 被视为无限远GT 不成立而 LT 成立。同一调用可能部分字段成功、部分失败。六、边界情况与错误处理场景行为Key 不存在按输入字段数返回多个 -2不创建 Key字段不存在该项返回 -2milliseconds 为 0该字段被立即删除返回 2milliseconds 为负数报参数范围错误milliseconds 不是整数报参数类型错误Key 是 String、List 等非 Hash报 WRONGTYPE 错误numfields 与实际字段数不符报语法错误需要注意HPEXPIRE 只作用于已存在的字段不会创建字段。若希望写入值的同时设置 TTL应使用 HSETEXRedis 8.0 起。七、客户端示例前提为已安装 redis-py 且服务端为 Redis 7.4 或更新版本。使用通用接口显式展示 FIELDS 语法。importredis rredis.Redis(hostlocalhost,port6379,decode_responsesTrue)ktutorial:{hpexpire}:pythontry:r.delete(k)r.hset(k,mapping{a:A,b:B})fields[a,b,missing]resultr.execute_command(HPEXPIRE,k,2000,FIELDS,len(fields),*fields)print(result)# [1, 1, -2]print(r.execute_command(HPTTL,k,FIELDS,2,a,b))# 约 [2000, 2000]print(r.execute_command(HPEXPIRE,k,0,FIELDS,1,a))# [2]立即删除print(r.hexists(k,a))# Falsefinally:r.delete(k)r.close()八、并发、重试与适用场景单条 HPEXPIRE 对多个字段原子执行但“先 HSET 写值再 HPEXPIRE 设期限”是两条独立调用中间可能有其他写入或客户端中断。需要一起生效时应使用事务或脚本并检查所有回复。相对 TTL 的无条件重试会从重试时刻重新计时可能无意延长有效期。若业务要求固定截止时间应改用 HPEXPIREAT。请求超时也不代表未执行重发前可先用 HPTTL 或 HPEXPIRETIME 检查字段当前状态。典型场景需要亚秒级精度的短缓存字段、限流窗口、短时令牌。控制每批字段数量与 Hash 规模不要把过期机制当作精确任务调度器。九、练习、排错与总结练习新建tutorial:{hpexpire}:exercise写入 a1、b2执行HPEXPIRE ... 1500 FIELDS 2 a b预期返回[1, 1]用 HPTTL 确认两个字段都有接近 1500 的毫秒值等待超过 1.5 秒后执行 HLEN预期返回0因为两个字段都已到期、Key 随之消失。排错要点unknown command 时确认服务端版本不低于 7.4返回 0 检查条件选项返回 -2 检查字段是否缺失或已到期返回 2 说明传入了 0 或已过去的时间HPTTL 返回 -1 表示字段永久有效而非命令失败。清理使用DEL tutorial:{hpexpire}:profile tutorial:{hpexpire}:cond tutorial:{hpexpire}:exercise。速记7.4 起支持、毫秒相对时间、FIELDS 必填、返回 -2/0/1/2、0 毫秒立即删除、不创建字段。