Redis Cluster Hash Tag 组织多 key 原子操作

Redis Cluster 要让多个 key 参与一次原子操作，关键不是把命令写成一行，而是先让这些 key 进入同一个 hash slot。最常用的做法是在相关 key 中放置相同的 Hash Tag，例如 user:{1001}:profile 和 user:{1001}:quota；Redis 只对花括号内的 1001 计算槽位。这样才能在集群中稳定使用 MSET、MULTI/EXEC 或 Lua 脚本。

把“同一业务对象”作为 Hash Tag，而不是把所有 key 都塞进一个固定标签；先保证同槽，再根据是否需要条件判断选择命令、事务或脚本。

• 同一组多 key 操作必须落在同一 hash slot，否则客户端或服务端会返回 CROSSSLOT。
• Hash Tag 只取第一个合法的花括号片段，标签应稳定、短小，并与业务聚合边界一致。
• MSET 适合直接写多个字符串；MULTI/EXEC 适合排队执行多条命令；Lua 适合把条件判断和更新放到服务端。

Redis Cluster 为什么要求多 key 同槽

Redis Cluster 把 16384 个 hash slot 分配给不同主节点。普通 key 会根据完整 key 名计算槽位，因此 user:1001:profile 与 user:1001:quota 不一定在同一节点。一个命令如果要同时访问它们，就可能需要跨节点协调，而 Redis Cluster 的常规多 key 操作并不为这种跨槽执行提供统一原子边界。

Hash Tag 改变的是“参与哈希的片段”，不是把数据复制到多个节点。只要 key 中存在合法的 {...}，Redis 会使用花括号内的内容计算槽位。下面这组命名把用户 1001 的资料、额度和锁绑定到相同槽位：

Hash Tag 怎样组织一组相关 key

标签的设计应对应一次操作的最小业务边界。以用户资料更新为例，使用 {1001} 作为标签比使用固定的 {all} 更合理：前者让每个用户分散到不同槽位，后者会把全站写入集中到一个槽位，形成热点。

# 用相同 Hash Tag 组织同一用户的相关 key；花括号内容决定槽位
MSET user:{1001}:profile "active" user:{1001}:quota "80"

# 下面两个 key 的标签不同，不能作为同一条集群多 key 操作的输入
MGET user:{1001}:profile user:{1002}:profile

上面的第二条命令不是“换一种写法就能跨槽”，而是业务边界不同。需要批量读取多个用户时，应由客户端按槽位拆分请求，或重新评估数据模型；不要为了绕过错误把所有用户改成同一个标签。

MSET、MULTI/EXEC 和 Lua 应该怎么选

MSET 本身就是多 key 的原子写入命令，适合“把几项字符串值一起写入”这种没有条件分支的场景。需要多条命令排队时，可以使用事务，但事务中的所有 key 仍需同槽：

# 事务内的所有 key 共享 {1001}，因此可以在同一槽位排队执行
MULTI
SET user:{1001}:profile "active"
INCR user:{1001}:version
EXEC

如果操作需要“读取旧值、判断条件、再更新多个 key”，Lua 更合适。脚本调用时应把所有会访问的 key 显式放进 KEYS，业务参数放进 ARGV，不要在脚本内拼接未声明的 key：

# KEYS[1] 和 KEYS[2] 必须带相同 Hash Tag；ARGV 只传业务值
EVAL "if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('SET', KEYS[2], ARGV[2]); return 1 end; return 0" 2 user:{1001}:version user:{1001}:profile 3 active

选择时可以记住三个判断：无条件批量字符串写入选 MSET；多条独立命令需要一次提交选 MULTI/EXEC；需要条件逻辑或读改写选 Lua。它们都不能突破跨槽限制。

出现 CROSSSLOT 或 TRYAGAIN 时怎么排查

先不要只盯着命令本身。逐个检查参与命令的 key 是否使用完全相同的标签，尤其注意一个 key 漏写花括号、标签大小写不同、标签中混入空格，以及客户端对 key 做了前缀改写。

# 查看两个 key 的槽位；槽位不同就不能直接做同一条多 key 操作
CLUSTER KEYSLOT user:{1001}:profile
CLUSTER KEYSLOT user:{1001}:quota

# 用 redis-cli 集群模式发送同槽命令；客户端负责跟随节点映射
redis-cli -c -h 127.0.0.1 -p 7000 MGET user:{1001}:profile user:{1001}:quota

如果槽位不同，通常是 key 设计问题，修正命名或按槽拆分。TRYAGAIN 则可能出现在相关槽位正在重分片时：源节点和目标节点对尚未稳定的数据视图不同。客户端应按重试策略稍后重试，但不要把无限重试当作一致性方案。

热点与重分片边界需要提前处理

同槽保证了原子边界，却也把同一标签下的读写集中到一个槽位。订单、购物车这类以用户为聚合根的数据通常适合使用用户 ID 作为标签；全局计数、全站排行榜或共享锁不应随意使用固定标签，否则扩容后仍只有一个节点承受主要流量。

重分片期间，多 key 操作在目标槽位迁移完成前可能短暂返回 TRYAGAIN。生产客户端应记录命令类型、标签和重试次数，超过上限后进入业务可识别的失败路径。若业务确实需要跨用户聚合，应改成分片读取后在应用层合并，或使用专门的聚合数据结构，而不是强行把不相关的 key 绑进一个标签。

常见问题 FAQ

Hash Tag 是不是必须写在 key 的开头？

不是。只要存在合法的花括号片段，Redis 会使用其中内容计算槽位，例如 profile:{1001}:name 也可以。为了可读性，通常把标签放在实体名后或 key 的稳定分段中。

两个 key 都有花括号但标签不同，可以放进 MULTI 吗？

不可以。{1001} 和 {1002} 产生的槽位通常不同；事务、Lua 和普通多 key 命令都要遵守同槽约束。

Hash Tag 能解决跨用户批量查询吗？

它解决的是同一标签内的多 key 原子操作，不是跨槽查询方案。跨用户请求应按槽位拆分，或设计面向查询的索引/聚合数据。