Redis HGETALL 大哈希的分批读取方案

Redis 的 HGETALL 没有分页参数，它会一次返回整个哈希。需要遍历大哈希时，可以改用 HSCAN，把返回的字段和值交给下游逐批处理；如果字段名已经确定，则优先按需读取，避免为几项数据扫描整份哈希。

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

下面以后台导出一份设备属性哈希为原创场景，展示读取配方。代码没有在本机连接 Redis 执行，不包含真实导出记录或性能测试。它适合允许非快照遍历的任务，不是账务式一致性导出方案。

先判断是遍历全部，还是只取已知字段

HGETALL 的工作量随哈希字段数增长，一次大响应还会占用网络和客户端解析内存。HSCAN 将完整迭代拆为多次请求，方便在调用之间安排消费与节流，但读取全部数据的总工作不会凭空消失。

如果页面只需要固定的几个属性，可以用 HMGET 指定字段；它解决的是“已知字段读取”。HSCAN 解决的是“字段名未知时遍历”。HGETALL 后在客户端切片，依然已经接收整份数据，不能达到分批获取的目的。

最小配方：游标负责延续，批次负责消费

HSCAN 请求由哈希键、输入游标和可选的 COUNT 提示组成，响应包含返回游标和字段值批次。第一次输入游标为 0；后续原样使用上一次返回的游标。只有返回游标为 0 才结束，当前批次为空并不表示结束。

COUNT 是工作量提示，不能解释为固定条数、最大条数或最大字节数。值很大时，即使字段数量不多，单次响应也可能很大。游标也不是页码，不能加一或据此计算完成百分比。

把逐批消费写成有预算的函数

下面函数接收已配置连接与超时的 redis-py 客户端。它不在内部构造连接，也不关闭调用方共享的连接池。COUNT 200 只是起始调优值，需结合实际延迟和响应体积调整。

import time

def export_hash(client, key, consume, *, count=200,
                max_calls=10000, budget_seconds=60.0):
    # 客户端应配置连接/读取超时；预算只在两次网络调用之间检查。
    if count = max_calls or time.monotonic() >= deadline:
            raise TimeoutError("扫描未完成，不能标记导出成功")

        # redis-py返回游标和字段字典；空批次也继续遵守游标规则。
        cursor, batch = client.hscan(key, cursor=cursor, count=count)
        calls += 1
        if batch:
            # 回调须同步完成或施加背压，不应把全部批次追加到内存列表。
            consume(batch)
        if cursor == 0:
            return {"completed": True, "calls": calls}

这是读取函数，consume 是业务提供的消费回调。回调异常和 Redis 异常会向上传播，调用方应把任务状态记为失败或未完成；示例没有吞掉错误后继续返回成功。循环预算无法中断正在阻塞的网络调用或回调，连接读取超时与下游超时仍要分别配置。

这里没有把所有批次合成一个字典，因此内存不必随完整哈希持续增长。但客户端仍需容纳当次完整响应；由于 COUNT 不是硬上限，这段代码不能保证严格的每批内存大小。若单个字段值已经过大，还要从值的存储设计着手。

重复字段和并发修改怎么处理

扫描可能重复返回同一字段。把字段身份作为幂等覆盖的键，通常比在内存里存下全部已见字段更适合大任务。消费回调可以把字段值批次写入有界缓冲背后的目标存储；目标端必须明确覆盖规则，不能每见一次字段就无条件增加计数或发一次通知。

幂等覆盖只解决重复副作用，不保证值来自同一时刻。扫描期间新增、删除或更新字段时，导出的结果可能混合不同时间的状态。若业务要求可重复的一致版本，应设计不可变版本键、受控写入窗口或其他有明确快照语义的数据来源，不能仅靠一个游标承诺一致性。

示例失败后没有实现可靠断点续传。保存游标之前要确保批次已被目标端确认；写入成功但游标未保存时，重试可能重放，所以仍需要幂等。键过期、被删除后重建或切换了版本时，旧游标也不能当作业务版本证明。

调优与变体按需求选择

先记录每次调用耗时、响应体积、消费耗时与任务状态，再调整 COUNT。增大 COUNT 可能减少往返次数，也可能增加单次工作；减小它也不能承诺响应硬上限。不要为追求“分批”把整个扫描循环塞入一个长 Lua 脚本，这会失去请求之间让出执行机会的目的。

相关问题

批次为空而游标非零，是否需要重头扫描？

不需要。继续用返回游标，尤其在使用 MATCH 时，空批次可以是正常情况。只有返回游标为零才完成本轮。

为什么去重集合也会造成内存增长？

若记录每个已见字段，去重集合本身就接近全部字段规模。优先考虑目标端按字段幂等覆盖，并单独定义并发更新的版本策略。

可以并发提交下一批请求吗？

同一条游标链的下次游标来自上次响应。先把串行读取、背压和失败语义做好，再考虑下游并发；无界并发消费容易把节省的读取内存重新堆在任务队列中。