Redis HPEXPIRE 怎样按毫秒设置哈希字段过期时间

如果一个 Redis hash 里同时放着登录 token、短期验证码和用户资料，给整个 key 设置过期时间往往太粗：验证码可能只需要 90 秒，资料却希望继续保留。Redis 7.4.0 起，可以用 HPEXPIRE 按字段设置毫秒级相对过期时间。

这篇只解决一个问题：怎样让指定哈希字段在 1500 毫秒后失效，并用返回数组和 HPTTL 读懂结果。官方地址：https://redis.io/docs/latest/commands/HPEXPIRE/

核心写法是 HPEXPIRE key milliseconds FIELDS numfields field...。它作用在字段，不是整个 hash key；每个字段对应一个返回值，成功设置返回 1，条件不满足返回 0，字段不存在返回 -2。

先把字段级 TTL 这件事看清楚

HPEXPIRE 的参数顺序很容易写错。除了 key 和毫秒数，还必须写 FIELDS 以及字段数量，再列出同样数量的字段。它和 PEXPIRE 的区别也很明确：后者控制整个 key，前者只控制 hash 内列出的字段。

服务端版本先确认到 Redis 7.4.0 或更高。官方文档将 HPEXPIRE 标记为 Redis Open Source 7.4.0 可用；如果旧服务返回 unknown command，先升级服务端，不要把它误判成 Go 参数问题。

用 go-redis 传入 1500 毫秒

go-redis/v9 将命令封装成 HPExpire，第三个参数使用 Go 的 time.Duration。客户端会按毫秒组装 Redis 命令，返回类型是整数切片，顺序与传入的字段顺序一致。

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/redis/go-redis/v9"
)

func main() {
    ctx := context.Background()
    rdb := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
    defer rdb.Close() // 程序结束时释放客户端资源

    // 先写入两个字段，便于观察只有 token 会单独过期。
    if err := rdb.HSet(ctx, "session:1001", "token", "abc", "profile", "basic").Err(); err != nil {
        panic(err) // 生产代码应把连接或命令错误交给上层处理
    }

    // time.Duration 用毫秒表达 1500，字段列表中的数量必须与后面的字段一致。
    result, err := rdb.HPExpire(ctx, "session:1001", 1500*time.Millisecond, "token").Result()
    if err != nil {
        panic(err) // 旧 Redis 或 key 类型错误会在这里返回
    }
    fmt.Println("HPEXPIRE result:", result) // 单字段成功时通常对应 [1]

    // HPTTL 同样按字段返回剩余毫秒，用来判断 TTL 是否确实挂在目标字段上。
    ttl, err := rdb.HPTTL(ctx, "session:1001", "token", "profile").Result()
    if err != nil {
        panic(err)
    }
    fmt.Println("HPTTL result:", ttl) // token 接近 1500，profile 为 -1 表示没有过期时间
}

这里没有给 profile 设置过期时间，所以 HPTTL 的第二个结果会是未设置 TTL 的状态；token 的剩余值会因网络往返和处理时间略小于 1500。不要把倒计时的自然减少当成设置失败。

用返回数组定位到底是哪一个字段没生效

一次 HPEXPIRE 可以处理多个字段，例如 token、profile 和一个不存在的字段。返回数组与字段一一对应：1 表示成功设置或更新，0 表示 NX、XX、GT、LT 条件未满足，-2 表示字段或 key 不存在；传入 0 毫秒或已经过去的时间会返回 2，对应字段会立即被删除。

排查时不要只看数组里是否出现 1，而要按字段下标逐项解释。比如 [1, 0, -2] 只有第一个字段完成设置，第二个字段被条件拦截，第三个字段根本不存在。

需要覆盖 TTL 时，选对条件参数

默认调用会直接设置或更新字段的过期时间。如果业务要求“只在没有 TTL 时初始化”，使用 NX；只允许给已有 TTL 的字段续期或调整，使用 XX；比较新旧过期点时使用 GT 或 LT。四个选项互斥，不能同时传多个。

// 只给还没有过期时间的 token 设置 900 毫秒，已有 TTL 时不覆盖。
result, err := rdb.HPExpireWithArgs(
    ctx,
    "session:1001",
    900*time.Millisecond,
    redis.HExpireArgs{NX: true}, // 条件由客户端转换成 Redis 的 NX 参数
    "token",
).Result()
if err != nil {
    panic(err) // 命令错误仍需向上层返回，不能把空结果当成成功
}
fmt.Println(result) // [1] 表示设置成功，[0] 表示已有 TTL，未覆盖

条件参数解决的是并发写入时的覆盖策略，不是锁。多个请求仍应根据返回值决定后续动作；如果业务需要强一致的读改写，再把这一步放进合适的事务或脚本边界。

几个看起来像“没生效”的原因

最后记住：FIELDS 后的数量必须和字段个数一致，key 必须确实是 hash；如果 key 是字符串、列表等其他类型，Redis 会返回类型错误。文章中的图是静态说明图，真正的剩余时间应以你自己的 HPTTL 返回为准。

相关问题

• HPEXPIRE 和 PEXPIRE 怎么选？前者按 hash 字段设置 TTL，后者按整个 key 设置 TTL。
• 想按绝对时间过期怎么办？查看 HPEXPIREAT，它使用 Unix 时间戳的毫秒形式。
• 怎样查看字段还剩多久？用 HPTTL 读毫秒，按字段顺序解释返回数组。