Redis HSCAN 的 COUNT 不是条数保证：游标遍历与批次内存控制

线上要清理一个存放用户偏好的 Redis Hash，最容易踩的坑是把 HSCAN key 0 COUNT 100 理解成“每次一定返回 100 个字段”。COUNT 只是 Redis 对本次迭代工作量的提示，返回数量可能更多，也可能更少；真正可靠的做法是持续消费游标，直到 Redis 返回游标 0，再在客户端自己控制每批处理量。

先看一次 COUNT 失效的现场

假设 user:preferences 里有几十万个字段，运维脚本希望每次取 100 个再处理。第一次返回 83 个，下一次返回 117 个，并不表示 Redis 出错。Hash 的底层编码、字段长度和当前游标位置都会影响一次迭代实际检查多少项。

127.0.0.1:6379> HSCAN user:preferences 0 COUNT 100
1) "8320"
2) 1) "theme:user-001"
   2) "dark"
   3) "lang:user-002"
   4) "zh-CN"

第一行是下一次调用要使用的游标，不是已扫描字段数。第二行开始才是字段和值的交替列表。把返回列表长度当成进度百分比，或者把 COUNT 当成分页大小，都会让清理脚本的进度判断失真。

游标循环才是完整遍历的收口条件

一次 HSCAN 只完成一段工作。客户端需要把响应中的新游标再次传给 HSCAN，并且无论本轮返回多少字段都继续循环。下面的 Python 示例保留了 Redis 原始游标语义：

import redis

r = redis.Redis(host="127.0.0.1", port=6379, decode_responses=True)
cursor = 0
seen = 0

while True:
    cursor, pairs = r.hscan("user:preferences", cursor=cursor, count=100)
    for field, value in pairs.items():
        # 这里处理一对 field/value，不把整个 Hash 读入内存
        if value == "legacy":
            r.hdel("user:preferences", field)
        seen += 1
    if cursor == 0:
        break

print(f"本轮扫描返回 {seen} 个字段")

这里的 seen 只能表示本轮收到的字段数量，不能直接等同于 Hash 在开始时的精确大小。脚本还要处理连接中断、单字段处理失败和运行时发生修改等情况，不能只在本地终端看到一次“循环结束”就把它当成一致性快照。

把扫描批次和业务批次分开

count=100 控制的是 Redis 端一次游标推进的工作提示；如果业务处理很慢，直接在这个循环里堆积待处理字段，客户端内存仍可能持续增长。更稳妥的方式是每轮拿到一小批就处理，必要时再用固定上限的队列承接：

如果单个字段处理要调用外部服务，可以把“扫描”与“处理”做成有界的生产消费流程：生产端每次最多放入 200 对，消费端处理完才继续请求下一轮。这样限制的是应用自己的内存和并发，而不是误以为 Redis 会替你提供严格分页。

Hash 在扫描期间变化时，结果怎么解释

HSCAN 属于渐进式迭代，不会为你冻结一个全量快照。如果扫描过程中新增、删除或修改字段，结果可能出现重复，也可能漏掉某些字段。对“删除值为 legacy 的旧偏好”这类幂等清理，重复通常可以接受；对“导出一份必须逐条一致的数据”，就不能把 HSCAN 当作事务快照。

还有一个实际风险：如果在遍历当前 Hash 时持续用 HDEL 修改同一个 key，脚本的业务目标必须是幂等的，并且要记录失败字段。遇到需要审计的迁移任务，更建议先把字段和值写入独立的任务表或文件，再做第二阶段变更，避免扫描和修改互相干扰。

生产脚本发布前的检查清单

• 是否把服务端返回的新游标写回下一次 HSCAN，而不是自行加偏移量。
• 是否只在游标等于 0 时宣布本轮完成。
• 是否给待处理队列设置容量上限，并对单字段失败保留重试或补偿记录。
• 是否明确扫描期间的数据变化允许重复、遗漏，还是必须先制作一致性副本。
• 是否在非高峰期运行，并为 Hash 过大、处理耗时过长设置停止阈值。

相关问题

HSCAN 的 COUNT 能不能当分页大小？

不能。COUNT 只是迭代工作量提示，客户端必须按返回的字段数量处理，不能依赖每页固定 100 条。

为什么 HSCAN 返回的字段会重复？

渐进式迭代允许在数据变化或底层重排时出现重复。需要精确结果时应让任务具备幂等性，或先建立一致性副本。

游标回到 0 就代表拿到了完整快照吗？

它代表这次迭代已经收口，不代表扫描期间没有新增、删除或修改。完整遍历与事务快照是两个不同目标。

把结论落到代码审查上

审查 Redis HSCAN 代码时，先找三个位置：新游标有没有覆盖旧游标，结束条件是不是严格判断 0，待处理数据有没有应用侧上限。只要这三处清楚，COUNT 的不确定返回量就不会再被误写成分页协议；至于一致性要求，则要单独选择快照、任务表或离线导出方案。