Redis HSCAN 怎么分页读取大 Hash 而不阻塞服务

一个 Hash 里有几十万字段时，别用 HGETALL 把整块数据一次性取回。更稳妥的做法是用 HSCAN key cursor COUNT count 做渐进遍历：每次拿到一小批字段和值，保存 Redis 返回的新游标，直到游标回到 0。

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

先把 HSCAN 的“分页”理解准确

HSCAN 的语法是 HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES]。第一次把 cursor 设为 0，Redis 返回一个新的 cursor 和本批结果；下一次把这个新 cursor 原样传回去。返回的 cursor 再次变成 0，才表示这轮迭代完成。

这里的分页只是“分批取数据”，不是 MySQL 那种固定的第 1 页、第 2 页。COUNT 200 不保证每次恰好返回 200 个元素，Redis 会把它当作工作量提示；小 Hash 甚至可能一次就结束，大 Hash 则需要多次请求。官方文档给出的复杂度是单次调用 O(1)，完整遍历合计为 O(N)，因此它能把大任务拆开，但不会让总工作量消失。

用 cursor 循环读取，而不是反复从 0 开始

下面这段命令适合先观察一个大 Hash 的遍历形态。每次执行后，把响应第一项的游标保存下来，再继续下一次。

# 从 0 开始，让 Redis 返回第一批字段和值
redis-cli HSCAN user:profile:all 0 COUNT 200

# 把上一次响应中的新游标继续传回；不要把它误当成页码 2
redis-cli HSCAN user:profile:all 7312 COUNT 200

# 当响应第一项变成 0，才结束本轮遍历
redis-cli HSCAN user:profile:all 0 COUNT 200

示例里的 7312 只是示意值，真实游标必须使用上一次 Redis 响应返回的值。生产代码通常维护 cursor 变量，并在每批处理完成后再保存进度；如果任务需要跨进程恢复，可把 key、cursor、扫描条件和业务批次号一起持久化。

用 COUNT、MATCH 和预算控制单批压力

COUNT 适合调节单次网络响应和应用处理时间，但不要把它当成精确限流器。每批真正的成本还包括反序列化、业务过滤、下游写入和日志输出。可以先从较小值开始，根据单批耗时逐步调大。

如果只需要一部分字段，可以加入 MATCH；如果只关心字段名，Redis 支持 NOVALUES，可以减少返回内容。注意 MATCH 是扫描结果过滤，不等价于对 Hash 建立索引；字段很多但匹配项很少时，仍可能需要走完整个游标空间。

数据变化时，怎样避免把扫描结果当成快照

HSCAN 适合渐进读取，不承诺给你一个冻结的 Hash 快照。扫描过程中字段可能被修改、删除或新增，因此同一个字段可能再次出现，某些变化也可能不在本轮结果里。不要在业务层按“第几页”做严格补偿，也不要因为看到重复字段就简单判定 Redis 出错。

更可靠的处理方式是让每个字段的消费动作幂等：以字段名和业务版本作为去重键，重复到达时覆盖同一结果；对必须完整导出的任务，可以先暂停写入，或给 Hash 建立导出版本，把扫描结果写入临时集合后再切换。扫描中断时保存 cursor 可以减少重头开始的成本，但恢复后仍要接受边界重复，最好从上一个已确认批次重新回放。

上线前至少记录三个指标：单批耗时、返回元素数和完整扫描轮次。若单批耗时超过业务预算，先降低 COUNT 或缩短每批的业务处理；若反复扫描仍没有回到 0，检查是否错误地把旧 cursor、字符串空值或多个消费者的 cursor 混用了。

常见问题

HSCAN 能保证每页固定 100 条吗？

不能。COUNT 只是提示，实际返回数量会随编码和数据状态变化。需要固定业务批次时，应在应用侧累积到预算后提交，而不是依赖 Redis 恰好返回固定条数。

扫描到一半删除字段会怎样？

本轮结果可能看不到被删除字段，也可能已经拿到它的旧值。导出或同步逻辑要有版本、时间点或幂等策略，不能把一次 HSCAN 当作事务快照。

什么时候可以直接用 HGETALL？

当 Hash 规模明确较小、响应体和应用内存都在预算内时，HGETALL 更简单。规模会增长或请求路径不能被大响应拖慢时，再采用 HSCAN。