Redis EXPIRETIME 命令详细教程EXPIRETIME用于获取 Key 的过期时间对应的 Unix 时间戳秒。与TTL返回剩余秒数不同EXPIRETIME返回的是绝对时间点便于在应用端直接判断 Key 何时过期、进行倒计时或与定时任务结合使用。本文基于 Redis 通用 Key 操作介绍EXPIRETIME。Redis 命令本身不区分大小写因此EXPIRETIME、expiretime和Expiretime的效果相同文档统一使用大写形式。EXPIRETIME自 Redis 7.0 起可用。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、命令概览1. 基本语法EXPIRETIME key参数说明参数说明key要查询过期时间戳的 Key返回值场景返回值Key 存在且有过期时间过期时间的 Unix 时间戳正整数秒Key 存在但无过期时间永久有效-1Key 不存在-22. 最简单的示例先写入一个值并设置过期时间再查看过期时间戳SET mykey Hello EX 3600 EXPIRETIME mykey返回类似(integer) 1724719123返回值是该 Key 过期时刻的 Unix 时间戳秒。用当前时间戳减去它结果等于TTL的值。二、EXPIRETIME 的返回结果1. Key 存在且有过期时间SET session:user:1001 active EX 1800 EXPIRETIME session:user:1001返回一个正整数如(integer) 1724722723表示该 Key 将在该 Unix 时间戳对应的时刻过期。2. Key 存在但无过期时间永久有效SET permanent-key forever EXPIRETIME permanent-key返回(integer) -1-1表示 Key 存在但没有设置过期时间永远不会自动过期。3. Key 不存在EXPIRETIME no-such-key返回(integer) -2-2表示 Key 不存在可能从未创建、已被删除或已过期被清理。4. 已过期的 Key已经过期但尚未被惰性/定期删除清理的 KeyEXPIRETIME返回-2视为不存在SET temp-key value EX 1等待 1 秒后执行EXPIRETIME temp-key返回(integer) -2Redis 在访问时进行惰性过期检查因此即使 Key 尚在内存中EXPIRETIME也会正确返回-2。5. 用绝对时间戳设置过期的 Key使用EXPIREAT或SET ... EXAT设置的 KeyEXPIRETIME返回的值就是设置时指定的时间戳SET promo:key summer-sale EXAT 1735689600 EXPIRETIME promo:key返回(integer) 1735689600用相对时间设置的 Key返回值也是绝对时间戳而非相对秒数SET cache:key value EX 3600 EXPIRETIME cache:key返回的是当前时间 3600 秒对应的绝对时间戳。三、EXPIRETIME 与 TTL 的关系EXPIRETIME返回过期时刻的绝对时间戳TTL返回剩余生存秒数。两者存在数学关系TTL(key) EXPIRETIME(key) - 当前Unix时间戳1. 对比示例SET mykey value EX 3600 TTL mykey EXPIRETIME mykey TIME返回类似TTL mykey - (integer) 3600 EXPIRETIME mykey - (integer) 1724722723 TIME - 1) 1724719123 2) 456789验证1724722723 - 1724719123 3600与TTL返回值一致。2. 何时使用 EXPIRETIME何时使用 TTL需求推荐命令原因判断 Key 是否快过期TTL直接得到剩余秒数显示倒计时TTL剩余秒数可直接用于倒计时获取 Key 何时过期绝对时间EXPIRETIME返回绝对时间戳与外部定时任务结合EXPIRETIME绝对时间便于跨系统对齐判断 Key 是永久还是临时TTL或EXPIRETIME均可返回-1即永久四、EXPIRETIME 与相关命令的区别1. EXPIRETIME 与 PEXPIRETIMEEXPIRETIME返回秒级时间戳PEXPIRETIME返回毫秒级时间戳SET mykey value PEX 3600000 EXPIRETIME mykey # 返回秒级时间戳如 1724722723 PEXPIRETIME mykey # 返回毫秒级时间戳如 1724722723456命令精度返回值示例EXPIRETIME key秒1724722723PEXPIRETIME key毫秒1724722723456需要毫秒精度时使用PEXPIRETIME。2. EXPIRETIME 与 TTL / PTTL命令返回内容单位EXPIRETIME key过期时刻的绝对时间戳秒PEXPIRETIME key过期时刻的绝对时间戳毫秒TTL key剩余生存时间秒PTTL key剩余生存时间毫秒SET mykey value EX 3600 EXPIRETIME mykey # 过期时间戳 TTL mykey # 剩余秒数 PTTL mykey # 剩余毫秒数 PEXPIRETIME mykey # 过期毫秒时间戳3. EXPIRETIME 与 EXPIREAT / EXPIRE 的区别EXPIREAT和EXPIRE是写命令用于设置过期时间EXPIRETIME是只读命令用于查询过期时间戳。命令操作类型作用EXPIREAT key timestamp写设置绝对过期时间EXPIRE key seconds写设置相对过期时间EXPIRETIME key只读查询过期时间戳4. 返回值对比总表状态EXPIRETIMETTLPTTLPEXPIRETIMEKey 存在且有过期过期秒级时间戳剩余秒数剩余毫秒数过期毫秒级时间戳Key 存在无过期-1-1-1-1Key 不存在-2-2-2-2五、EXPIRETIME 与不同数据类型EXPIRETIME作用于整个 Key所有数据类型String、Hash、List、Set、Sorted Set、Stream 等的行为一致。HSET user:1001 name Alice age 30 EXPIRE user:1001 3600 EXPIRETIME user:1001RPUSH queue:jobs job-a job-b EXPIRE queue:jobs 1800 EXPIRETIME queue:jobsSADD tags redis python EXPIRE tags 7200 EXPIRETIME tags返回值都是 Key 的过期时间戳与数据类型无关。六、过期时间的刷新与 EXPIRETIME1. 覆盖式更新后的反映对已有过期时间的 Key 再次执行EXPIRE或EXPIREATEXPIRETIME返回的值会更新为新的过期时间戳SET mykey value EX 3600 EXPIRETIME mykey # 返回 timestamp1 EXPIREAT mykey 1767225600 EXPIRETIME mykey # 返回 17672256002. SET 会清除过期时间使用SET命令覆盖 Key 的值时不带EX/PX/EXAT/PXAT过期时间被清除EXPIRETIME返回-1SET mykey old EX 3600 EXPIRETIME mykey # 返回正数 SET mykey new EXPIRETIME mykey # 返回 -13. PERSIST 后的反映PERSIST移除过期时间后EXPIRETIME返回-1SET mykey value EX 3600 PERSIST mykey EXPIRETIME mykey # 返回 -14. 各命令对 EXPIRETIME 结果的影响操作EXPIRETIME 返回值变化EXPIRE key seconds更新为新的过期时间戳EXPIREAT key timestamp更新为指定的时间戳PEXPIRE key ms更新为新的过期时间戳PEXPIREAT key timestamp更新为指定的时间戳SET key value无选项变为-1清除过期SET key value EX seconds更新为新的过期时间戳SET key value EXAT timestamp更新为指定的时间戳PERSIST key变为-1移除过期INCR/LPUSH/HSET等不影响保持原值GETEX key取决于参数可修改或清除过期时间七、事务、Pipeline 与并发场景1. 在事务中使用EXPIRETIME可以放入事务队列MULTI SET mykey value EX 3600 EXPIRETIME mykey TTL mykey EXECEXEC执行后返回各命令的结果。2. 只读特性与并发安全EXPIRETIME是只读命令不修改任何数据不会影响其他客户端的操作。多个客户端同时调用EXPIRETIME是安全的。3. 并发场景下的注意事项由于EXPIRETIME返回的是查询时刻的过期时间戳如果在两次查询之间有其他客户端修改了 Key 的过期时间如EXPIRE、SET、PERSIST返回值可能不同。这属于正常的并发行为先查再判断的多步流程不是原子操作。需要原子地检查过期时间并执行操作时使用 Lua 脚本localexpireredis.call(EXPIRETIME,KEYS[1])ifexpire0thenreturnexpireelsereturnredis.call(EXPIRE,KEYS[1],ARGV[1])end4. Pipeline 批量查询需要查询大量 Key 的过期时间戳时可以使用 Pipeline 批量发送EXPIRETIME命令减少网络往返。八、在常见客户端中的使用方式1. redis-cliredis-cli SET mykeyvalueEX3600redis-cli EXPIRETIME mykey redis-cli SET permanentforeverredis-cli EXPIRETIME permanent redis-cli EXPIRETIME no-such-key分别返回正数时间戳、-1、-2。2. Pythonredis-pyimportredis clientredis.Redis(hostlocalhost,port6379,decode_responsesTrue)client.set(mykey,value,ex3600)# 获取过期时间戳expire_timeclient.expiretime(mykey)print(expire_time)# 如 1724722723# 永久 Keyclient.set(permanent,forever)print(client.expiretime(permanent))# -1# 不存在的 Keyprint(client.expiretime(no-such-key))# -23. Node.jsnode-redisimport{createClient}fromredis;constclientcreateClient();awaitclient.connect();awaitclient.set(mykey,value,{EX:3600});constexpireTimeawaitclient.expireTime(mykey);console.log(expireTime);// 如 1724722723awaitclient.set(permanent,forever);console.log(awaitclient.expireTime(permanent));// -1console.log(awaitclient.expireTime(no-such-key));// -2awaitclient.quit();4. JavaJedistry(JedisjedisnewJedis(localhost,6379)){jedis.set(mykey,value,SetParams.setParams().ex(3600));// 获取过期时间戳longexpireTimejedis.expireTime(mykey);System.out.println(expireTime);// 如 1724722723// 永久 Keyjedis.set(permanent,forever);System.out.println(jedis.expireTime(permanent));// -1// 不存在的 KeySystem.out.println(jedis.expireTime(no-such-key));// -2}九、典型使用场景1. 倒计时显示获取 Key 的绝对过期时间戳在客户端计算剩余时间并显示倒计时SET flash-sale:product active EX 3600 EXPIRETIME flash-sale:product客户端用EXPIRETIME返回的时间戳减去当前时间戳得到剩余秒数并显示。2. 过期时间对齐多个 Key 需要在同一时刻过期时用EXPIRETIME确认是否已对齐EXPIRETIME cache:a EXPIRETIME cache:b EXPIRETIME cache:c如果返回值不同用EXPIREAT统一调整EXPIREAT cache:a 1735689600 EXPIREAT cache:b 1735689600 EXPIREAT cache:c 17356896003. 监控与告警监控系统查询 Key 的过期时间戳判断是否即将过期并提前告警EXPIRETIME session:critical如果返回的时间戳接近当前时间戳触发告警提醒续期。4. 与外部定时任务结合应用端获取 Key 的过期时间戳后在对应时刻注册定时任务处理过期事件EXPIRETIME task:cleanup5. 数据生命周期审计定期扫描设置了过期时间的 Key审计过期时间是否合理SCAN 0 EXPIRETIME key1 EXPIRETIME key2十、性能与使用建议时间复杂度O(1)。EXPIRETIME是只读命令ACL 类别为keyspace、read、fast不会修改数据不会触发通知。性能优异频繁调用不会对 Redis 造成压力。只需判断 Key 是否存在时用EXISTS语义更清晰需要过期时间信息时用EXPIRETIME。需要剩余秒数时用TTL需要绝对时间戳时用EXPIRETIME两者可互相换算。EXPIRETIME对永久 Key 返回-1、对不存在的 Key 返回-2与TTL的返回值约定一致便于统一处理。集群模式下EXPIRETIME作用于单个 Key不受哈希槽限制。Redis 7.0 以下版本不支持EXPIRETIME调用会返回错误。低版本场景可用TTL加上当前时间戳间接计算。十一、常见问题排查问题 1EXPIRETIME 返回 -2 但 Key 应该存在按以下顺序检查是否连接到了正确的 Redis 实例、端口和逻辑数据库不同SELECT库中 Key 相互独立。Key 是否已经过期用TTL确认返回-2表示不存在。Key 名称是否包含不可见字符、前后空格或大小写差异。Key 是否被其他客户端删除或覆盖SET不带选项会清除过期时间但 Key 仍存在如果返回-2则 Key 本身不存在。EXISTS mykey TTL mykey TYPE mykey问题 2EXPIRETIME 返回 -1 但预期有过期时间可能的原因在设置过期时间后执行了SET不带EX/EXAT等选项覆盖了 Key 的值导致过期时间被清除。执行了PERSIST命令移除了过期时间。查询的 Key 与设置过期的 Key 不是同一个名称差异。问题 3EXPIRETIME 返回的时间戳与预期不符可能的原因使用了EXPIRE相对秒数而非EXPIREAT绝对时间戳设置过期返回的时间戳是设置时刻 相对秒数。过期时间被其他客户端用EXPIRE、EXPIREAT或SET ... EX更新过。时区理解错误返回的是 UTC Unix 时间戳不是本地时间。问题 4Redis 7.0 以下版本报错EXPIRETIME从 Redis 7.0 开始支持。低版本调用会返回错误ERR unknown command EXPIRETIME替代方案使用TTL key获取剩余秒数加上当前时间戳得到过期时间戳redis-cli TTL mykey# 获取剩余秒数redis-cli TIME# 获取当前时间戳# 过期时间戳 当前时间戳 TTL问题 5EXPIRETIME 与 PEXPIRETIME 返回值不一致EXPIRETIME返回秒级时间戳PEXPIRETIME返回毫秒级时间戳。两者数值相差约 1000 倍但表示的是同一过期时刻EXPIRETIME mykey # 如 1724722723 PEXPIRETIME mykey # 如 1724722723456PEXPIRETIME EXPIRETIME * 1000 毫秒部分。十二、完整练习下面的示例演示从设置过期时间、查询过期时间戳、对比 TTL 与 EXPIRETIME、验证不同状态返回值到与SET、PERSIST、EXPIREAT等命令配合使用的完整流程DEL demo:key DEL demo:perm DEL demo:short # 基本用法设置相对过期查询绝对时间戳 SET demo:key hello EX 3600 EXPIRETIME demo:key TTL demo:key TIME # 验证关系EXPIRETIME 当前时间戳 TTL # 如 EXPIRETIME1724722723, TIME1724719123, TTL3600 # 永久 Key 返回 -1 SET demo:perm forever EXPIRETIME demo:perm TTL demo:perm # 不存在的 Key 返回 -2 EXPIRETIME demo:noexist TTL demo:noexist # 用绝对时间戳设置过期 EXPIREAT demo:key 1767225600 EXPIRETIME demo:key # SET 清除过期时间 SET demo:key new value EXPIRETIME demo:key # SET ... EXAT 设置过期时间戳 SET demo:key with ttl EXAT 1735689600 EXPIRETIME demo:key # PERSIST 后返回 -1 PERSIST demo:key EXPIRETIME demo:key # 过期后返回 -2 SET demo:short gone EX 1 # 等待 1 秒后执行 # EXPIRETIME demo:short # TTL demo:short # 对比 EXPIRETIME 与 PEXPIRETIME SET demo:precision value EX 3600 EXPIRETIME demo:precision PEXPIRETIME demo:precision预期结果EXPIRETIME demo:key返回正数时间戳TTL demo:key返回约3600EXPIRETIME - TIME约等于TTL。EXPIRETIME demo:perm返回-1TTL demo:perm返回-1。EXPIRETIME demo:noexist返回-2TTL demo:noexist返回-2。EXPIREAT demo:key 1767225600后EXPIRETIME demo:key返回1767225600。SET demo:key new value后EXPIRETIME demo:key返回-1。SET demo:key with ttl EXAT 1735689600后EXPIRETIME demo:key返回1735689600。PERSIST demo:key后EXPIRETIME demo:key返回-1。过期后EXPIRETIME demo:short返回-2。EXPIRETIME与PEXPIRETIME返回值相差约 1000 倍表示同一过期时刻。十三、命令速查表需求命令返回值类型获取过期时间戳秒EXPIRETIME key秒级 Unix 时间戳获取过期时间戳毫秒PEXPIRETIME key毫秒级 Unix 时间戳获取剩余生存时间秒TTL key剩余秒数获取剩余生存时间毫秒PTTL key剩余毫秒数判断 Key 是否存在EXISTS key0 或 1获取 Key 的数据类型TYPE key类型字符串设置秒级过期时间EXPIRE key seconds0 或 1设置绝对过期时间秒EXPIREAT key timestamp0 或 1设置毫秒级过期时间PEXPIRE key ms0 或 1设置绝对过期时间毫秒PEXPIREAT key timestamp0 或 1原子设置值和过期时间戳SET key value EXAT timestampOK移除过期时间PERSIST key0 或 1获取服务器当前时间TIME秒 微秒总结EXPIRETIME的核心作用是返回 Key 过期时刻的 Unix 时间戳秒便于应用端获取绝对过期时间点EXPIRETIME key使用时重点注意四点返回值约定与TTL一致正数表示过期时间戳-1表示永久有效-2表示 Key 不存在。EXPIRETIME返回的是绝对时间戳TTL返回的是剩余秒数两者可互相换算。SET不带选项会清除过期时间EXPIRE/EXPIREAT会更新过期时间PERSIST会移除过期时间EXPIRETIME能反映这些变化。EXPIRETIME从 Redis 7.0 开始支持低版本可用TTL加当前时间戳间接计算过期时间戳。 Redis命令：EXPIRETIME
Redis EXPIRETIME 命令详细教程EXPIRETIME用于获取 Key 的过期时间对应的 Unix 时间戳秒。与TTL返回剩余秒数不同EXPIRETIME返回的是绝对时间点便于在应用端直接判断 Key 何时过期、进行倒计时或与定时任务结合使用。本文基于 Redis 通用 Key 操作介绍EXPIRETIME。Redis 命令本身不区分大小写因此EXPIRETIME、expiretime和Expiretime的效果相同文档统一使用大写形式。EXPIRETIME自 Redis 7.0 起可用。资料合集https://pan.quark.cn/s/10e98d308913、https://pan.quark.cn/s/f56bc69c5338一、命令概览1. 基本语法EXPIRETIME key参数说明参数说明key要查询过期时间戳的 Key返回值场景返回值Key 存在且有过期时间过期时间的 Unix 时间戳正整数秒Key 存在但无过期时间永久有效-1Key 不存在-22. 最简单的示例先写入一个值并设置过期时间再查看过期时间戳SET mykey Hello EX 3600 EXPIRETIME mykey返回类似(integer) 1724719123返回值是该 Key 过期时刻的 Unix 时间戳秒。用当前时间戳减去它结果等于TTL的值。二、EXPIRETIME 的返回结果1. Key 存在且有过期时间SET session:user:1001 active EX 1800 EXPIRETIME session:user:1001返回一个正整数如(integer) 1724722723表示该 Key 将在该 Unix 时间戳对应的时刻过期。2. Key 存在但无过期时间永久有效SET permanent-key forever EXPIRETIME permanent-key返回(integer) -1-1表示 Key 存在但没有设置过期时间永远不会自动过期。3. Key 不存在EXPIRETIME no-such-key返回(integer) -2-2表示 Key 不存在可能从未创建、已被删除或已过期被清理。4. 已过期的 Key已经过期但尚未被惰性/定期删除清理的 KeyEXPIRETIME返回-2视为不存在SET temp-key value EX 1等待 1 秒后执行EXPIRETIME temp-key返回(integer) -2Redis 在访问时进行惰性过期检查因此即使 Key 尚在内存中EXPIRETIME也会正确返回-2。5. 用绝对时间戳设置过期的 Key使用EXPIREAT或SET ... EXAT设置的 KeyEXPIRETIME返回的值就是设置时指定的时间戳SET promo:key summer-sale EXAT 1735689600 EXPIRETIME promo:key返回(integer) 1735689600用相对时间设置的 Key返回值也是绝对时间戳而非相对秒数SET cache:key value EX 3600 EXPIRETIME cache:key返回的是当前时间 3600 秒对应的绝对时间戳。三、EXPIRETIME 与 TTL 的关系EXPIRETIME返回过期时刻的绝对时间戳TTL返回剩余生存秒数。两者存在数学关系TTL(key) EXPIRETIME(key) - 当前Unix时间戳1. 对比示例SET mykey value EX 3600 TTL mykey EXPIRETIME mykey TIME返回类似TTL mykey - (integer) 3600 EXPIRETIME mykey - (integer) 1724722723 TIME - 1) 1724719123 2) 456789验证1724722723 - 1724719123 3600与TTL返回值一致。2. 何时使用 EXPIRETIME何时使用 TTL需求推荐命令原因判断 Key 是否快过期TTL直接得到剩余秒数显示倒计时TTL剩余秒数可直接用于倒计时获取 Key 何时过期绝对时间EXPIRETIME返回绝对时间戳与外部定时任务结合EXPIRETIME绝对时间便于跨系统对齐判断 Key 是永久还是临时TTL或EXPIRETIME均可返回-1即永久四、EXPIRETIME 与相关命令的区别1. EXPIRETIME 与 PEXPIRETIMEEXPIRETIME返回秒级时间戳PEXPIRETIME返回毫秒级时间戳SET mykey value PEX 3600000 EXPIRETIME mykey # 返回秒级时间戳如 1724722723 PEXPIRETIME mykey # 返回毫秒级时间戳如 1724722723456命令精度返回值示例EXPIRETIME key秒1724722723PEXPIRETIME key毫秒1724722723456需要毫秒精度时使用PEXPIRETIME。2. EXPIRETIME 与 TTL / PTTL命令返回内容单位EXPIRETIME key过期时刻的绝对时间戳秒PEXPIRETIME key过期时刻的绝对时间戳毫秒TTL key剩余生存时间秒PTTL key剩余生存时间毫秒SET mykey value EX 3600 EXPIRETIME mykey # 过期时间戳 TTL mykey # 剩余秒数 PTTL mykey # 剩余毫秒数 PEXPIRETIME mykey # 过期毫秒时间戳3. EXPIRETIME 与 EXPIREAT / EXPIRE 的区别EXPIREAT和EXPIRE是写命令用于设置过期时间EXPIRETIME是只读命令用于查询过期时间戳。命令操作类型作用EXPIREAT key timestamp写设置绝对过期时间EXPIRE key seconds写设置相对过期时间EXPIRETIME key只读查询过期时间戳4. 返回值对比总表状态EXPIRETIMETTLPTTLPEXPIRETIMEKey 存在且有过期过期秒级时间戳剩余秒数剩余毫秒数过期毫秒级时间戳Key 存在无过期-1-1-1-1Key 不存在-2-2-2-2五、EXPIRETIME 与不同数据类型EXPIRETIME作用于整个 Key所有数据类型String、Hash、List、Set、Sorted Set、Stream 等的行为一致。HSET user:1001 name Alice age 30 EXPIRE user:1001 3600 EXPIRETIME user:1001RPUSH queue:jobs job-a job-b EXPIRE queue:jobs 1800 EXPIRETIME queue:jobsSADD tags redis python EXPIRE tags 7200 EXPIRETIME tags返回值都是 Key 的过期时间戳与数据类型无关。六、过期时间的刷新与 EXPIRETIME1. 覆盖式更新后的反映对已有过期时间的 Key 再次执行EXPIRE或EXPIREATEXPIRETIME返回的值会更新为新的过期时间戳SET mykey value EX 3600 EXPIRETIME mykey # 返回 timestamp1 EXPIREAT mykey 1767225600 EXPIRETIME mykey # 返回 17672256002. SET 会清除过期时间使用SET命令覆盖 Key 的值时不带EX/PX/EXAT/PXAT过期时间被清除EXPIRETIME返回-1SET mykey old EX 3600 EXPIRETIME mykey # 返回正数 SET mykey new EXPIRETIME mykey # 返回 -13. PERSIST 后的反映PERSIST移除过期时间后EXPIRETIME返回-1SET mykey value EX 3600 PERSIST mykey EXPIRETIME mykey # 返回 -14. 各命令对 EXPIRETIME 结果的影响操作EXPIRETIME 返回值变化EXPIRE key seconds更新为新的过期时间戳EXPIREAT key timestamp更新为指定的时间戳PEXPIRE key ms更新为新的过期时间戳PEXPIREAT key timestamp更新为指定的时间戳SET key value无选项变为-1清除过期SET key value EX seconds更新为新的过期时间戳SET key value EXAT timestamp更新为指定的时间戳PERSIST key变为-1移除过期INCR/LPUSH/HSET等不影响保持原值GETEX key取决于参数可修改或清除过期时间七、事务、Pipeline 与并发场景1. 在事务中使用EXPIRETIME可以放入事务队列MULTI SET mykey value EX 3600 EXPIRETIME mykey TTL mykey EXECEXEC执行后返回各命令的结果。2. 只读特性与并发安全EXPIRETIME是只读命令不修改任何数据不会影响其他客户端的操作。多个客户端同时调用EXPIRETIME是安全的。3. 并发场景下的注意事项由于EXPIRETIME返回的是查询时刻的过期时间戳如果在两次查询之间有其他客户端修改了 Key 的过期时间如EXPIRE、SET、PERSIST返回值可能不同。这属于正常的并发行为先查再判断的多步流程不是原子操作。需要原子地检查过期时间并执行操作时使用 Lua 脚本localexpireredis.call(EXPIRETIME,KEYS[1])ifexpire0thenreturnexpireelsereturnredis.call(EXPIRE,KEYS[1],ARGV[1])end4. Pipeline 批量查询需要查询大量 Key 的过期时间戳时可以使用 Pipeline 批量发送EXPIRETIME命令减少网络往返。八、在常见客户端中的使用方式1. redis-cliredis-cli SET mykeyvalueEX3600redis-cli EXPIRETIME mykey redis-cli SET permanentforeverredis-cli EXPIRETIME permanent redis-cli EXPIRETIME no-such-key分别返回正数时间戳、-1、-2。2. Pythonredis-pyimportredis clientredis.Redis(hostlocalhost,port6379,decode_responsesTrue)client.set(mykey,value,ex3600)# 获取过期时间戳expire_timeclient.expiretime(mykey)print(expire_time)# 如 1724722723# 永久 Keyclient.set(permanent,forever)print(client.expiretime(permanent))# -1# 不存在的 Keyprint(client.expiretime(no-such-key))# -23. Node.jsnode-redisimport{createClient}fromredis;constclientcreateClient();awaitclient.connect();awaitclient.set(mykey,value,{EX:3600});constexpireTimeawaitclient.expireTime(mykey);console.log(expireTime);// 如 1724722723awaitclient.set(permanent,forever);console.log(awaitclient.expireTime(permanent));// -1console.log(awaitclient.expireTime(no-such-key));// -2awaitclient.quit();4. JavaJedistry(JedisjedisnewJedis(localhost,6379)){jedis.set(mykey,value,SetParams.setParams().ex(3600));// 获取过期时间戳longexpireTimejedis.expireTime(mykey);System.out.println(expireTime);// 如 1724722723// 永久 Keyjedis.set(permanent,forever);System.out.println(jedis.expireTime(permanent));// -1// 不存在的 KeySystem.out.println(jedis.expireTime(no-such-key));// -2}九、典型使用场景1. 倒计时显示获取 Key 的绝对过期时间戳在客户端计算剩余时间并显示倒计时SET flash-sale:product active EX 3600 EXPIRETIME flash-sale:product客户端用EXPIRETIME返回的时间戳减去当前时间戳得到剩余秒数并显示。2. 过期时间对齐多个 Key 需要在同一时刻过期时用EXPIRETIME确认是否已对齐EXPIRETIME cache:a EXPIRETIME cache:b EXPIRETIME cache:c如果返回值不同用EXPIREAT统一调整EXPIREAT cache:a 1735689600 EXPIREAT cache:b 1735689600 EXPIREAT cache:c 17356896003. 监控与告警监控系统查询 Key 的过期时间戳判断是否即将过期并提前告警EXPIRETIME session:critical如果返回的时间戳接近当前时间戳触发告警提醒续期。4. 与外部定时任务结合应用端获取 Key 的过期时间戳后在对应时刻注册定时任务处理过期事件EXPIRETIME task:cleanup5. 数据生命周期审计定期扫描设置了过期时间的 Key审计过期时间是否合理SCAN 0 EXPIRETIME key1 EXPIRETIME key2十、性能与使用建议时间复杂度O(1)。EXPIRETIME是只读命令ACL 类别为keyspace、read、fast不会修改数据不会触发通知。性能优异频繁调用不会对 Redis 造成压力。只需判断 Key 是否存在时用EXISTS语义更清晰需要过期时间信息时用EXPIRETIME。需要剩余秒数时用TTL需要绝对时间戳时用EXPIRETIME两者可互相换算。EXPIRETIME对永久 Key 返回-1、对不存在的 Key 返回-2与TTL的返回值约定一致便于统一处理。集群模式下EXPIRETIME作用于单个 Key不受哈希槽限制。Redis 7.0 以下版本不支持EXPIRETIME调用会返回错误。低版本场景可用TTL加上当前时间戳间接计算。十一、常见问题排查问题 1EXPIRETIME 返回 -2 但 Key 应该存在按以下顺序检查是否连接到了正确的 Redis 实例、端口和逻辑数据库不同SELECT库中 Key 相互独立。Key 是否已经过期用TTL确认返回-2表示不存在。Key 名称是否包含不可见字符、前后空格或大小写差异。Key 是否被其他客户端删除或覆盖SET不带选项会清除过期时间但 Key 仍存在如果返回-2则 Key 本身不存在。EXISTS mykey TTL mykey TYPE mykey问题 2EXPIRETIME 返回 -1 但预期有过期时间可能的原因在设置过期时间后执行了SET不带EX/EXAT等选项覆盖了 Key 的值导致过期时间被清除。执行了PERSIST命令移除了过期时间。查询的 Key 与设置过期的 Key 不是同一个名称差异。问题 3EXPIRETIME 返回的时间戳与预期不符可能的原因使用了EXPIRE相对秒数而非EXPIREAT绝对时间戳设置过期返回的时间戳是设置时刻 相对秒数。过期时间被其他客户端用EXPIRE、EXPIREAT或SET ... EX更新过。时区理解错误返回的是 UTC Unix 时间戳不是本地时间。问题 4Redis 7.0 以下版本报错EXPIRETIME从 Redis 7.0 开始支持。低版本调用会返回错误ERR unknown command EXPIRETIME替代方案使用TTL key获取剩余秒数加上当前时间戳得到过期时间戳redis-cli TTL mykey# 获取剩余秒数redis-cli TIME# 获取当前时间戳# 过期时间戳 当前时间戳 TTL问题 5EXPIRETIME 与 PEXPIRETIME 返回值不一致EXPIRETIME返回秒级时间戳PEXPIRETIME返回毫秒级时间戳。两者数值相差约 1000 倍但表示的是同一过期时刻EXPIRETIME mykey # 如 1724722723 PEXPIRETIME mykey # 如 1724722723456PEXPIRETIME EXPIRETIME * 1000 毫秒部分。十二、完整练习下面的示例演示从设置过期时间、查询过期时间戳、对比 TTL 与 EXPIRETIME、验证不同状态返回值到与SET、PERSIST、EXPIREAT等命令配合使用的完整流程DEL demo:key DEL demo:perm DEL demo:short # 基本用法设置相对过期查询绝对时间戳 SET demo:key hello EX 3600 EXPIRETIME demo:key TTL demo:key TIME # 验证关系EXPIRETIME 当前时间戳 TTL # 如 EXPIRETIME1724722723, TIME1724719123, TTL3600 # 永久 Key 返回 -1 SET demo:perm forever EXPIRETIME demo:perm TTL demo:perm # 不存在的 Key 返回 -2 EXPIRETIME demo:noexist TTL demo:noexist # 用绝对时间戳设置过期 EXPIREAT demo:key 1767225600 EXPIRETIME demo:key # SET 清除过期时间 SET demo:key new value EXPIRETIME demo:key # SET ... EXAT 设置过期时间戳 SET demo:key with ttl EXAT 1735689600 EXPIRETIME demo:key # PERSIST 后返回 -1 PERSIST demo:key EXPIRETIME demo:key # 过期后返回 -2 SET demo:short gone EX 1 # 等待 1 秒后执行 # EXPIRETIME demo:short # TTL demo:short # 对比 EXPIRETIME 与 PEXPIRETIME SET demo:precision value EX 3600 EXPIRETIME demo:precision PEXPIRETIME demo:precision预期结果EXPIRETIME demo:key返回正数时间戳TTL demo:key返回约3600EXPIRETIME - TIME约等于TTL。EXPIRETIME demo:perm返回-1TTL demo:perm返回-1。EXPIRETIME demo:noexist返回-2TTL demo:noexist返回-2。EXPIREAT demo:key 1767225600后EXPIRETIME demo:key返回1767225600。SET demo:key new value后EXPIRETIME demo:key返回-1。SET demo:key with ttl EXAT 1735689600后EXPIRETIME demo:key返回1735689600。PERSIST demo:key后EXPIRETIME demo:key返回-1。过期后EXPIRETIME demo:short返回-2。EXPIRETIME与PEXPIRETIME返回值相差约 1000 倍表示同一过期时刻。十三、命令速查表需求命令返回值类型获取过期时间戳秒EXPIRETIME key秒级 Unix 时间戳获取过期时间戳毫秒PEXPIRETIME key毫秒级 Unix 时间戳获取剩余生存时间秒TTL key剩余秒数获取剩余生存时间毫秒PTTL key剩余毫秒数判断 Key 是否存在EXISTS key0 或 1获取 Key 的数据类型TYPE key类型字符串设置秒级过期时间EXPIRE key seconds0 或 1设置绝对过期时间秒EXPIREAT key timestamp0 或 1设置毫秒级过期时间PEXPIRE key ms0 或 1设置绝对过期时间毫秒PEXPIREAT key timestamp0 或 1原子设置值和过期时间戳SET key value EXAT timestampOK移除过期时间PERSIST key0 或 1获取服务器当前时间TIME秒 微秒总结EXPIRETIME的核心作用是返回 Key 过期时刻的 Unix 时间戳秒便于应用端获取绝对过期时间点EXPIRETIME key使用时重点注意四点返回值约定与TTL一致正数表示过期时间戳-1表示永久有效-2表示 Key 不存在。EXPIRETIME返回的是绝对时间戳TTL返回的是剩余秒数两者可互相换算。SET不带选项会清除过期时间EXPIRE/EXPIREAT会更新过期时间PERSIST会移除过期时间EXPIRETIME能反映这些变化。EXPIRETIME从 Redis 7.0 开始支持低版本可用TTL加当前时间戳间接计算过期时间戳。