Redis Hash 怎样只更新一个字段并返回旧值

如果业务要把 Redis Hash 的一个字段从旧状态改成新状态，同时把旧值交给日志、审计或后续事件处理，直接调用 HSET 不够：它会覆盖字段，但返回的是本次新增字段的数量，不是被覆盖前的值。Redis 8.0 及以上可以用 HGETDEL 处理“读取旧值并删除字段”的场景；如果目标是“读取旧值后写入新值”，更稳妥的做法是把 HGET 和 HSET 放进同一个 Lua 脚本。

真正的单字段替换要把“读旧值、写新值、返回旧值”看成一个原子动作。HGETDEL 适合取值并删除，不能直接把字段替换成新值；需要保留字段并写入新值时，用 Lua 把两条命令放在 Redis 服务端一次执行。

官方地址：https://redis.io/docs/latest/commands/hgetdel/

下面按一个高并发状态字段的例子拆开说明：先区分命令语义，再给出 Redis 8+ 与旧版本的选择，最后补上客户端代码中最容易漏掉的空值和兼容处理。

先确认你要的是替换还是删除

“更新一个字段并返回旧值”很容易和“取出字段旧值后删除它”混在一起。两者都涉及旧值，但最终状态不同：

这个区分决定了后面该选哪条路径。如果把 HGETDEL 当成普通更新命令，最后会发现旧值拿到了，但 Hash 中的字段也不见了。

Redis 8+ 用 HGETDEL 处理取值并删除

HGETDEL 的语义是“返回 Hash 字段的值，然后把这些字段删除”。它从 Redis 8.0 开始提供，单字段调用时复杂度为 O(1)；如果一次指定多个字段，复杂度按字段数量增长。单字段命令可以这样写：

# 只取出 status 的旧值，并删除 status 字段
redis-cli HGETDEL order:1001 FIELDS 1 status

如果 status 原来是 pending，返回值就是这个旧值，同时该字段从 order:1001 中消失。字段不存在时返回空值，不要把它误判为字符串形式的“null”。

这个命令特别适合一次性消费、领取后移除或清理 Hash 字段的业务。例如某个待处理标记只允许被取走一次，读取和删除必须在 Redis 端完成，调用方不需要先 HGET 再单独 HDEL。

但它不适合“把 pending 改成 paid 后仍保留 status”的替换任务，因为删除动作是命令语义的一部分。此时继续使用它会让状态字段消失。

需要保留字段时，用 Lua 把读写放进同一边界

Redis 8+ 仍没有一个把“Hash 读取旧值、写入新值、返回旧值”直接表达成单条普通命令的通用写法。对需要保留字段的替换，可以让 Lua 脚本在 Redis 服务端顺序执行两条命令：

-- 先读取旧值，再写入新值；脚本整体在 Redis 内一次执行
local old = redis.call('HGET', KEYS[1], ARGV[1])
redis.call('HSET', KEYS[1], ARGV[1], ARGV[2])
return old

调用时把 Hash key 放进 KEYS[1]，把字段名、字段新值依次放进 ARGV[1] 和 ARGV[2]：

# KEYS[1] 是 Hash key；ARGV 依次是 field、new value
redis-cli EVAL "local old = redis.call('HGET', KEYS[1], ARGV[1]); redis.call('HSET', KEYS[1], ARGV[1], ARGV[2]); return old" 1 order:1001 status paid

脚本返回 pending 时，order:1001.status 已经变成 paid。读和写都在同一脚本执行期间完成，其他客户端不会插入一条命令到两步之间，因此不会出现“返回的是旧值 A，但最终覆盖了别的请求刚写入的值”这类窗口。

如果业务还有“只有旧值等于某个状态才允许更新”的条件，也应把判断放进脚本里，让判断、写入和返回值保持一个原子边界，而不是在客户端先判断再发第二条命令。

Go 客户端怎样返回旧值

在 Go 项目中可以使用 go-redis 的 Eval 调用脚本。示例只让脚本接收一个 key，并把字段名和新值作为参数传入；这样 Redis Cluster 也能清楚知道脚本操作的 key。

package main

import (
    "context"
    "fmt"

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

var replaceHashField = redis.NewScript(`
-- 返回旧值，并把同一个字段替换为新值
local old = redis.call("HGET", KEYS[1], ARGV[1])
redis.call("HSET", KEYS[1], ARGV[1], ARGV[2])
return old
`)

func main() {
    ctx := context.Background()
    client := redis.NewClient(&redis.Options{Addr: "localhost:6379"})
    defer client.Close() // 示例结束时释放连接池资源

    old, err := replaceHashField.Run(ctx, client, []string{"order:1001"}, "status", "paid").Result()
    if err != nil {
        // 真实服务中按项目策略记录错误并决定是否重试。
        panic(err)
    }
    fmt.Printf("old=%v\\n", old)
}

Result() 返回的可能是字符串，也可能是 nil。nil 通常表示字段原本不存在，而不是 Redis 把旧值保存成了空字符串；如果业务允许空字符串作为合法值，就需要结合 HEXISTS 或把脚本返回结果设计成“是否存在 + 旧值”的结构。

脚本只使用一个 Hash key，集群调用时不要在同一个脚本中随意加入不同槽位的 key。若必须操作多个 key，需要通过 hash tag 让它们落在同一槽位，并让脚本参数与客户端的 key 列表保持一致。

并发、兼容和返回值边界

Redis 版本：HGETDEL 的官方文档标注为 Redis 8.0.0 起可用。部署环境低于这个版本时，不要直接发送该命令；普通替换场景使用 Lua，或者在明确可以接受竞态的前提下拆成客户端两次调用。

空值判断：字段不存在、旧值为空字符串和脚本返回错误是三种不同情况。不要只用字符串比较把它们混为一类；跨语言客户端还要注意 bulk nil 的映射类型。

HSET 的返回值：HSET 返回新增字段的数量，已有字段被覆盖时通常返回 0。这个数字表示字段是否新建，不代表旧值，也不能用来推断旧值内容。

多字段更新：如果一次要替换多个字段并返回多个旧值，脚本应明确返回数组顺序，调用方也要按固定字段列表解释返回结果。不要依赖 Hash 的遍历顺序来建立字段与旧值的关系。

失败处理：Lua 脚本返回错误时，客户端不要把部分业务结果当成成功状态继续落库。对于网络超时，要结合幂等键或状态机判断是否重试，不能仅凭“没有拿到旧值”就再次写入。

常见问题

HGETDEL 能不能先返回旧值再写入新值？ 不能。它的后半段是删除字段；要保留字段并替换成新值，应使用 Lua 组合 HGET 和 HSET。

直接 HGET 后 HSET 有什么问题？ 两条客户端命令之间可能被其他请求插入，读到的旧值和最终写入结果不再属于同一次原子操作。

HSET 返回 0 是否说明更新失败？ 不一定。它通常表示字段已存在并被覆盖；要判断命令是否执行成功，还要结合客户端错误返回。

字段不存在时 Lua 会写入新值吗？ 上面的脚本会把旧值返回为 nil，同时执行 HSET 创建该字段。如果“不存在时禁止创建”，需要在脚本中先判断旧值存在性再决定是否写入。