Redis Cluster hash tag多键事务为什么没有落到同一节点为什么结果为空或不符合预期

如果 Redis Cluster 中的多键事务报 CROSSSLOT Keys in request don't hash to the same slot，或者命令没有按预期读到数据，先不要把问题归因于事务本身。最常见的原因是参与事务的 key 没有使用同一个有效 hash tag，或者客户端拼接出的实际 key 与设计稿不一致。

官方地址：https://redis.io/

本文只解决一个边界：怎样让一组确实需要一起路由的 key 落到同一 hash slot，并用它支撑 Redis Cluster 的多键命令或事务。它不把 Redis Cluster 变成跨节点分布式事务。

先看槽位：hash tag 到底改变了什么

Redis Cluster 默认会对整个 key 计算槽位。hash tag 改变的是参与计算的文本：当 key 中出现一对有效花括号时，Redis 使用第一对花括号之间的非空内容计算槽位。

例如，下面两个 key 的 tag 都是 user-42，所以它们可以共享槽位：

cart:{user-42}:items
cart:{user-42}:coupon

而 cart:{user-42}:items 与 cart:{user-43}:coupon 的 tag 不同，不能把它们当作同一组多键事务。空花括号 {} 也不能提供一个有效 tag；这时应按完整 key 检查槽位。花括号里的空格、大小写和连字符也会改变 tag，{User-42} 与 {user-42} 不是同一个值。

图1：这是结构说明图，不是 Redis 控制台截图；查看相同 tag 如何把两个 key 绑定到同一个 hash slot。

先确认“同槽位”，再讨论“同节点”

在 Cluster 中，多键命令和事务的第一道约束是相关 key 必须位于同一 hash slot。slot 当前由哪个主节点负责，是集群拓扑的一部分；resharding 或故障转移时，slot 的负责节点可能变化。因此，hash tag 的承诺是“这些 key 使用同一槽位”，不是永久绑定某一台物理机器。

可以用官方命令分别查看槽位。下面只展示排查命令，不把未执行的输出写成运行证据：

# 分别检查两个业务 key 的槽位；输出的整数应由目标集群返回
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT 'cart:{user-42}:items'
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT 'cart:{user-42}:coupon'

# 这个 key 使用了不同 tag，排查时应把它视为另一组路由
redis-cli -c -h 127.0.0.1 -p 7000 CLUSTER KEYSLOT 'cart:{user-43}:coupon'

如果前两个槽位不同，优先打印客户端最终发送的完整 key，而不是只看模板变量。常见失误包括一个函数使用 {user-42}，另一个函数把 tag 放在了 key 末尾，或者某个分支漏掉了花括号。

为什么会“结果为空”或看起来不符合预期

槽位相同只说明请求可以被路由到同一处，不能保证 key 已经存在，也不能改变命令的返回语义。可以按下面的顺序缩小问题：

1. 先查实际 key：写入与读取必须使用完全一致的 tag、前缀和后缀。把模板展开后的 key 记录下来，比记录用户 ID 更有用。
2. 再查存在性：事务里读取一个不存在的 key，返回空值是正常结果；它不是 hash tag 失败的证据。
3. 最后查事务返回：EXEC 返回的是每条排队命令对应的结果。某一条命令执行报错，不等于其它命令已经自动回滚。

另一个容易误判的场景是客户端连接到了某个节点。Cluster 节点不会替客户端代理全部请求，客户端可能收到 MOVED 或 ASK 重定向。应使用支持 Cluster 拓扑的客户端，并让它处理路由；不要把单节点客户端当成 Cluster 客户端使用。

把排查结果落到 Go 事务代码

下面用 go-redis 的 ClusterClient 表达同槽位事务。关键点不是某个方法名，而是所有涉及的 key 都共享 {user-42}。示例还保留了错误处理，避免把 CROSSSLOT 或执行阶段的错误吞掉：

package main

import (
    "context"
    "fmt"

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

func saveCart(ctx context.Context, client *redis.ClusterClient, userID, item string) error {
    // tag 只放稳定的业务分片键；同一事务中的 key 必须复用它。
    tag := "{user-" + userID + "}"
    itemsKey := "cart:" + tag + ":items"
    countKey := "cart:" + tag + ":count"

    _, err := client.TxPipelined(ctx, func(pipe redis.Pipeliner) error {
        // TxPipelined 会用 MULTI/EXEC 组织命令；这里只加入同槽位 key。
        pipe.SAdd(ctx, itemsKey, item)
        pipe.HIncrBy(ctx, countKey, "total", 1)
        return nil
    })
    if err != nil {
        // CROSSSLOT、拓扑错误或执行错误都要交给上层决定是否重试。
        return fmt.Errorf("保存购物车事务失败: %w", err)
    }
    return nil
}

如果业务确实需要更新不同 tag 的 key，就不能靠 hash tag“修复”它。应改成单 key 事件、按用户聚合后的单槽位模型，或由业务层设计补偿流程。把多个不相关对象强行塞进同一个 tag，会让某个热点用户的所有数据集中到同一槽位。

图2：这是 Go Redis Cluster 事务结构说明图；重点查看客户端事务组件与同槽位 key 的关系，不代表真实运行截图。

一张表记住排查边界

常见问题

hash tag 能保证两个 key 永远在同一台机器吗？

不能。它保证的是相同 hash slot；slot 在集群拓扑调整时可能迁移到另一台主节点。应用只应依赖同槽位路由约束，不应把节点地址写死。

把所有 key 都写成同一个 tag 可以吗？

技术上可能造成热点，但不一定是好设计。tag 应绑定真正需要一起执行的最小业务边界；跨用户共享的数据不要为了绕过 CROSSSLOT 而集中到一个 tag。

总结

排查 Redis Cluster 多键事务时，先展开完整 key，再用 CLUSTER KEYSLOT 对照。有效 hash tag 让相关 key 共享 slot，ClusterClient 才能把事务交给同一个槽位负责方；它不提供跨节点事务，也不会把空结果自动变成数据。最后把 CROSSSLOT、重定向和 EXEC 内部错误分别处理，问题通常就能落到具体的键名或客户端路由上。