Redis HSCAN 用 MATCH 和 COUNT 分批筛选 Hash 字段

大型 Hash 不适合用 HGETALL 一次性拉回应用层。更稳妥的做法是让 HSCAN 从游标 0 开始，每轮带上 MATCH 和 COUNT，把返回的下一个游标继续传回 Redis，直到游标再次变成 0。这里最容易误判的是 COUNT：它是工作量提示，不是“本轮必定返回多少个字段”的承诺。

先把 HSCAN 的三件事分开

HSCAN key cursor [MATCH pattern] [COUNT count] [NOVALUES] 里，cursor 决定遍历位置，MATCH 决定哪些字段可以出现在结果中，COUNT 只给 Redis 一个本轮工作量的方向。完整遍历的复杂度是 O(N)，单次调用是 O(1)；因此它解决的是“分摊一次性读取压力”，不是把 Hash 变成有序分页表。

用游标循环筛选大型 Hash

下面的命令把字段名以 profile: 开头的成员分批找出来。即使某一轮返回空列表，也要继续使用 Redis 返回的游标；因为过滤发生在扫描之后，匹配稀疏时出现空批次是正常现象。

# 从 0 开始扫描 user:1001 这个 Hash，只筛选 profile: 开头的字段
redis-cli HSCAN user:1001 0 MATCH 'profile:*' COUNT 100

# 假设返回下一个游标 128；下一轮必须使用这个游标
redis-cli HSCAN user:1001 128 MATCH 'profile:*' COUNT 100

# 最后一轮返回游标 0，才表示本次完整遍历结束
redis-cli HSCAN user:1001 0 MATCH 'profile:*' COUNT 100

示例中的最后一行只是说明结束形态：真实返回的终止游标必须由上一轮响应给出，不能手工把游标改成 0。在程序里应当把响应拆成“下一游标”和“字段/值数组”，而不是用返回数量判断是否完成。

COUNT 不是分页大小，空批次也要继续

当 MATCH 很窄时，Redis 可能已经扫描了一段内部结构，但这一段没有字段命中，于是返回空数组和一个非零游标。若代码写成“结果为空就 break”，就会漏掉后面的匹配字段。COUNT 可以在延迟和总调用次数之间做取舍：值较小，单轮更轻但请求次数可能增加；值较大，单轮可能更重，也不会保证严格返回相同数量。

如果业务只需要字段名，可以使用 NOVALUES，减少值的网络传输；如果后续马上要使用字段值，则保留默认的字段/值对返回。不要把 COUNT 100 误写成“每页 100 条”，也不要把 HSCAN 当成带稳定顺序的分页接口。

生产使用前的四项检查

• 结束条件：只在下一游标为 0 时结束循环。
• 幂等性：扫描期间字段可能被修改，处理动作要允许重复或记录去重键。
• 负载控制：结合单轮耗时、客户端超时和业务高峰调整 COUNT，必要时在轮次之间让出调度。
• 字段模式：确认 *、?、字符组等 glob 语义符合字段命名规则，避免把正则写法直接搬过来。

常见问题

HSCAN 返回空数组是不是扫描结束

不是。只要返回游标不是 0，就应继续下一轮；空数组可能只是当前扫描段没有匹配字段。

COUNT 能不能保证每次返回 100 个字段

不能。它是实现层面的工作量提示，Redis 允许每轮返回少于、接近或多于这个数量。

HSCAN 能不能保证字段只返回一次

不能把它当成严格去重快照。集合在遍历期间发生变化时，应用层应采用幂等处理；对稳定集合也不要用返回顺序承载业务语义。

把 cursor 当作协议状态、把 MATCH 当作字段过滤、把 COUNT 当作负载提示，HSCAN 才适合用来渐进式处理大型 Hash。