Redis HSCAN 怎样按模式增量读取字段

线上有一个很大的 Hash，需要只处理名称以 profile: 开头的字段。直接使用 HGETALL 会把整个 Hash 一次性搬到客户端，既占内存，也让单次任务的耗时不可控。这时应该把读取拆成多个小回合：HSCAN 负责游标，MATCH 负责字段名筛选，COUNT 只负责提示每轮大致处理量。

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

先把 HSCAN 看成游标工作流

HSCAN 的命令形态是 HSCAN key cursor [MATCH pattern] [COUNT count]。第一次调用使用 0，返回结果包含两部分：下一次调用要使用的游标，以及本轮读到的字段和值。只要返回游标不是 0，任务就还没有完成。

先用 redis-cli 看最小调用关系。下面的注释只解释参数用途，不把返回数量当成固定分页：

# 从 0 开始扫描 user:profile 这个 Hash
redis-cli HSCAN user:profile 0

# 继续使用上一轮返回的游标，并只匹配 profile: 开头的字段
redis-cli HSCAN user:profile 17 MATCH 'profile:*' COUNT 50

返回的第一个值可能是 17、42 等任意游标值，不应自己递增，也不应把它当成字段偏移量。第二次调用必须原样带上 Redis 返回的游标；只有它重新变为 0，才可以结束这个完整遍历。

把 MATCH、COUNT 放进可恢复处理循环

MATCH 只约束字段名，支持 Redis 的 glob 风格模式：* 表示任意长度字符，? 表示单个字符，方括号可以表示字符集合。它不是正则表达式，也不会按业务条件解析字段值。

COUNT 50 的含义是“尽量按这个工作量组织一次返回”，不是“每页恰好返回 50 个字段”。Redis 文档还特别说明，筛选发生在扫描到元素之后，因此一个回合可能得到空数组；这时仍然要保存新游标并继续扫描。

在 Go 客户端中，可以把“游标推进”和“业务处理”分成两个阶段。这样即使某一轮没有命中字段，也不会错误退出：

package main

import (
	"context"
	"fmt"

	"github.com/redis/go-redis/v9"
)

func scanProfileFields(ctx context.Context, client *redis.Client) error {
	var cursor uint64
	for {
		// MATCH 只筛字段名；COUNT 是每轮工作量提示，不是精确页大小。
		items, next, err := client.HScan(ctx, "user:profile", cursor, "profile:*", 50).Result()
		if err != nil {
			// 保留原始错误，让上层决定重试或记录当前检查点。
			return fmt.Errorf("hscan user:profile: %w", err)
		}

		// items 是 field/value 交替排列的切片；空切片仍然要推进游标。
		for i := 0; i+1 

如果业务处理耗时较长，可以在自己的任务表或消息中记录 next，把它作为下一次任务的恢复游标。但它只适合“继续一次扫描”的场景，不是跨数据版本的稳定分页游标；Hash 在扫描期间发生大量新增、删除或修改时，结果不能当成事务快照。

触发失败时，先区分空批次和真正结束

生产任务里最容易出现三个误判：

如果任务需要重试，优先重试当前命令或恢复到业务记录的游标，不要为了“补一页”改成 HGETALL。扫描期间数据变化还可能让同一字段被看到多次，或者某些变化中的字段不在这次结果里；需要严格一致的批处理，应先建立版本化快照或使用更适合事务语义的数据结构。

上线前的参数和通知清单

• 确认 key 确实是 Hash，字段模式使用的是 glob 语法而非正则语法。
• 把 COUNT 按单轮业务处理成本调整，避免把它写成必须精确满足的分页协议。
• 记录最近一次游标、已处理字段数和最后错误；空批次不直接触发“扫描失败”告警。
• 只有游标为 0 才发送“本轮完成”通知；网络错误或业务处理错误要走重试/人工处理回路。

常见问题

HSCAN MATCH 为什么有时连续几轮都没有结果？

因为 MATCH 在扫描到字段之后再筛选，当前回合扫描到的字段可能都不符合模式。继续使用返回游标即可，不能把空数组当成结束信号。

COUNT 设置为 100，能保证每轮返回 100 个字段吗？

不能。COUNT 是提示值，Redis 会根据内部结构组织返回；小 Hash 甚至可能一次返回全部字段，业务代码应按真实数组处理。

HSCAN 能替代稳定分页吗？

它适合降低单次读取压力的增量遍历，不提供按字段名排序的稳定分页语义。若数据在扫描过程中变化，不要把游标当成跨快照的分页 token。