不能在Lua中循环调用HSCAN，因Redis单线程执行且默认lua-time-limit为5秒，大Hash迭代上千次必超时触发BUSY错误，且无状态恢复机制；必须由客户端管理游标、分页与终止判断。
Redis 的 HSCAN 本身已支持游标式遍历，但直接在业务层反复调用容易暴露网络往返、游标管理混乱、并发竞争等问题；用 Lua 封装不是为了“替代 HSCAN”，而是把游标推进、结果截断、边界控制收进原子上下文，避免客户端侧逻辑出错导致重复或遗漏。
为什么不能直接在 Lua 里循环调用 hscan 直到完成？
Lua 脚本在 Redis 中有最大执行时间限制（默认 lua-time-limit = 5000 毫秒），而大 Hash 可能含数十万 field，一次 HSCAN 返回 100 条，要迭代上千次 —— 这种纯 while 循环极易超时，触发 BUSY 错误，脚本被强制中断，且无状态恢复机制。
所以封装目标不是“扫完”，而是“安全地扫一段”，把游标和分页逻辑交给客户端协调：
- 每次 Lua 调用只做一次
HSCAN，返回最多count条 + 下一个游标 - 不维护全局状态，不依赖 Redis 内存变量（如
redis.call("set", ...)存游标） - 客户端负责重试、游标传递、终止判断（比如游标变 0）
EVAL 脚本中如何正确调用 hscan 并控制返回大小？
关键点在于：Lua 中 redis.call("hscan", ...) 返回的是两元素数组 {next_cursor, {k1,v1,k2,v2,...}}，需手动解包、截断、重组。不能直接 return 原始结果，否则客户端解析困难。
示例脚本（传入 key、当前游标、count）：
local key = KEYS[1]
local cursor = tonumber(ARGV[1])
local count = tonumber(ARGV[2]) or 10
<p>local res = redis.call("hscan", key, cursor, "COUNT", count)
local next_cursor = res[1]
local raw_pairs = res[2]</p><p>-- 提取键值对，每两个元素一组
local result = {}
for i = 1, #raw_pairs, 2 do
table.insert(result, {raw_pairs[i], raw_pairs[i+1]})
end</p><p>return {next_cursor, result}说明：
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
- 客户端调用时用
EVAL <script> 1 <key> <cursor> <count> - 返回是 Lua table，Redis 自动序列化为数组：第一个元素是下个游标（string），第二个是键值对数组
- 不加
MATCH参数，如需过滤，可扩展为ARGV[3]传入 pattern
客户端调用时游标怎么传、什么时候停？
游标是字符串，但语义上是“下一批从哪开始”。初始游标必须是 "0"（不是数字 0），后续严格使用上一轮返回的 next_cursor 字符串值。
终止条件只有一个：next_cursor == "0"。注意：
- 不要比较
next_cursor == 0（类型错） - 不要因某次返回空数组就停止 ——
HSCAN可能在游标非 0 时返回空（比如中间没匹配项），但仍有后续 - 如果业务需要“精确获取全部”，必须持续调用直到游标为
"0"，哪怕最后几轮只返回 1 条
Python 示例片段（伪代码）：
cursor = "0"
while cursor != "0":
cursor, items = redis.eval(script, 1, key, cursor, 50)
process(items)这个方案会比纯客户端 HSCAN 更快或更省资源吗？
不会。Lua 封装不减少网络次数，也不降低计算量，它只把“解析响应体 + 提取 kv 对”这步从客户端移到服务端，好处是：
- 避免客户端用错误方式解析
HSCAN返回的扁平数组（常见 bug：把["a","1","b","2"]当成字符串列表处理） - 统一 count 截断逻辑，防止客户端传错
COUNT导致单次返回过大（比如传 10000，在慢网中引发超时） - 便于后续加字段过滤、类型校验等轻量逻辑，而不用改客户端
真正影响性能的是 count 值选择：太小（如 10）→ 请求多、RTT 累积高；太大（如 1000）→ 单次响应大、Redis 线程阻塞久。建议从 50–200 起调，观察 slowlog 和 client output buffer。
最易被忽略的一点：Hash 结构本身是否合理。如果真需要频繁全量扫描，说明数据建模可能有问题 —— 把不该塞进一个 key 的东西硬塞进 HASH，再怎么优化扫描也治标不治本。
