Redis Lua 怎样避免脚本访问跨槽 key

在 Redis Cluster 中，Lua 脚本不是“连到任意节点就能访问所有 key”。脚本里涉及的 key 需要由客户端明确传入，并且一次脚本执行访问的 key 通常必须属于同一个 hash slot。出现 CROSSSLOT Keys in request don't hash to the same slot 时，优先检查 key 参数和命名方式，而不是给脚本拼接动态 key。

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

本文只讨论 Lua 的 key 参数与槽位关系：把 key 放进 KEYS，把普通业务值放进 ARGV，再用统一的 hash tag 让同一业务对象的 key 共槽。

先分清是参数边界还是槽位冲突

Redis 的 EVAL 参数顺序是脚本、numkeys、key 列表、普通参数列表。numkeys 决定从第三个参数开始有多少项进入 Lua 的 KEYS，剩余项才进入 ARGV。

这里有两个容易混在一起的问题：

把脚本访问的 key 全部放进 KEYS

Lua 脚本应只访问调用方显式提供的 key。以“设置值并删除旧值”为例，脚本需要两个 key，调用时把 numkeys 写成 2；业务值“新内容”属于 ARGV，不参与槽位计算。

# 两个完整 key 放在 numkeys 后，业务值放在所有 key 之后
redis-cli -c EVAL "
  -- KEYS 只保存 key 名，ARGV 保存普通业务参数
  redis.call('SET', KEYS[1], ARGV[1])
  redis.call('DEL', KEYS[2])
  return 1
" 2 "profile:{u100}:current" "profile:{u100}:old" "active"

脚本内部不要根据 ARGV 拼出另一个未声明的 key，也不要从某个 Redis 集合里读出 key 名后继续访问。这样写既破坏了脚本的输入契约，也让 Cluster 客户端无法在发送前根据 key 选择正确节点。

KEYS 还应该保持“完整 key 名”的语义。不要把 profile:{u100} 当作前缀，再在 Lua 里拼接 :current；直接传入最终会被访问的两个 key，更容易审查和迁移。

用相同 hash tag 让相关 key 共槽

Redis Cluster 默认对完整 key 计算槽位；如果 key 中出现非空的 {...} 片段，槽位只按花括号内的内容计算。因此 profile:{u100}:current 和 profile:{u100}:old 会因为共同的 u100 被安排到同一槽。

# 两个 key 的 tag 相同，适合作为同一 Lua 调用的 KEYS
profile:{u100}:current
profile:{u100}:old

# tag 不同，不能假设它们位于同一槽
profile:{u100}:current
profile:{u200}:current

hash tag 的内容应选择业务上的“原子操作单元”，例如用户 ID、订单号或租户 ID。不要把一个超大租户的全部数据都塞进同一个 tag，否则虽然可以避免跨槽，却可能把热点集中在单个槽位。

无法共槽时，调整数据模型而不是硬绕过

如果一次操作天然要修改两个不同用户、两个不同租户或两个独立聚合的数据，就不要强行把它们塞进一个 Cluster Lua 脚本。常见处理方式是把操作拆成两个单槽步骤，再由业务层记录状态、补偿或重试；另一种方式是重新设计聚合边界，让真正需要原子更新的数据共享一个稳定 tag。

Redis 文档还提供脚本标志来描述某些执行能力，但这不应成为默认的跨槽方案：声明给脚本的 key 仍然需要满足路由和输入契约，跨槽访问会让数据迁移、故障处理和客户端路由更复杂。先解决 key 的归属，再考虑是否需要更特殊的脚本能力。

上线前可以按下面的清单检查设计：

• 每个被脚本读写的 key 是否都作为 EVAL 的 key 参数传入？
• numkeys 是否与 key 参数数量一致，业务值是否全部位于 ARGV？
• 同一次脚本调用的 key 是否共享同一个非空 hash tag？
• hash tag 是否代表合理的原子操作单元，是否会制造单槽热点？
• 无法共槽的操作是否已经拆分，并设计了失败后的补偿路径？

常见问题

把 key 放入 ARGV 能避免跨槽吗？

不能。ARGV 只是普通参数，不能替代 KEYS。只要脚本会访问某个 key，就应把完整 key 名作为 key 参数传入，并让客户端据此路由。

只要 key 名里有大括号就一定共槽吗？

不一定。只有满足 Redis Cluster hash tag 规则的非空花括号片段才会参与共槽计算；最稳妥的做法是让同一原子操作的 key 使用完全一致的 {业务标识}。

单机 Redis 也要设计 hash tag 吗？

单机模式通常没有 Cluster 的跨槽限制，但提前采用稳定的 key 命名仍有助于未来迁移到集群。是否使用 hash tag，要结合业务聚合边界和热点分布一起决定。

总结

避免 Redis Lua 跨槽错误可以归纳为三件事：显式声明全部 key、严格区分 KEYS 与 ARGV、用同一 hash tag 组织需要原子访问的 key。若业务对象本来就不属于同一个槽位，拆分操作或调整数据模型通常比绕过 Cluster 约束更可靠。