Redis的哈希类型经常用来存储对象字段，但当一个哈希键包含几十万甚至上百万个字段时，使用HGETALL一次性拉取所有内容会让Redis主线程长时间占用CPU和内存，客户端也可能因为响应体过大而超时。HSCAN提供了一种基于游标的迭代方式，每次只返回少量元素，同时不阻塞其他命令的执行。理解HSCAN的工作机制，对于生产环境中处理大哈希结构至关重要。
HSCAN命令的基本语法和游标模型
HSCAN命令的基本形式是 HSCAN key cursor [MATCH pattern] [COUNT count]。第一次调用时游标传0，Redis返回一个新游标和一批字段值对。客户端需要把新游标作为下一次调用的参数，直到返回的游标变为0，表示遍历结束。下面是一个redis-cli中的示例：
HSCAN user:profile 0 COUNT 100 1) "17" 2) 1) "name" 2) "Alice" 3) "age" 4) "30" 5) "email" 6) "alice@ipipp.com"
返回结果的第一行是下一个游标，第二行是一个数组，字段和值成对出现。这里COUNT只是提示Redis每次尽量返回100个字段，实际返回数量可能多一些或少一些，尤其在哈希表发生rehash的时候。游标并不是数据偏移量，而是一个不透明的状态值，客户端不需要理解它的含义，只需要原样传回即可。
HSCAN的无状态设计意味着Redis服务端不会保存遍历进度。如果客户端在迭代过程中崩溃，重新从0开始即可，不会留下脏状态。这也是HSCAN适合分布式环境的原因：每个客户端独立维护自己的游标，互不干扰。代价是客户端必须自己控制循环终止条件，一旦忘记更新游标就可能陷入死循环。
为什么HSCAN可能返回重复元素？如何保证遍历完整性
很多开发者第一次使用HSCAN时会惊讶地发现，同一个字段可能在两次迭代中都出现，或者有些字段在整个遍历过程中被漏掉。这并不是bug，而是Redis为降低阻塞而做出的设计取舍。当哈希键的底层数据结构是hashtable时，Redis使用反向二进制迭代算法，游标实际上标记的是哈希表桶索引的位反转状态。在遍历过程中，如果哈希发生增删操作，桶的分布就会改变，已经扫描过或尚未扫描的桶可能重新映射，导致元素重复或遗漏。
例如，客户端正在扫描第100号桶时，另一个客户端向哈希新增了一个字段，这个字段经过哈希后落到了第50号桶（已经扫描过），那么本次遍历就不会再返回它。反过来，如果删除操作让某个字段的桶位置移动到尚未扫描的区域，这个字段就可能被再次返回。所以HSCAN不提供数据库级别的快照隔离。
要获得完整的遍历结果，常见的做法有两种：一是接受重复，在客户端使用Set或Map去重；二是先执行一次BGSAVE生成RDB快照，再在从节点上对快照数据进行遍历，但这会引入额外复杂度。对于大多数业务场景，比如批量导出数据或统计分析，允许少量重复并不会影响最终结果，客户端去重是成本最低的方案。
MATCH、COUNT、NOVALUES参数的实际作用与性能影响
MATCH参数用于在服务端对字段名进行glob模式匹配，例如 MATCH user:* 只返回以user:开头的字段。需要注意的是，匹配发生在Redis服务端，但Redis不会因为MATCH而提前结束遍历，它仍然会扫描整个哈希表，只是对不匹配的字段做了过滤。如果匹配率很低，客户端可能连续多次收到空结果，白白消耗网络往返。因此MATCH适合在字段名有规律且匹配率较高的场景使用。
COUNT参数是每次迭代期望返回的元素数量上限。在Redis 7.0之前，COUNT只是一个提示值，实际返回的元素数量可能会超过COUNT，因为Redis会一次性扫描完整的一个桶，桶内元素多时就会超过COUNT。从Redis 7.0开始，HSCAN对COUNT的处理有所优化，返回数量更贴近请求值。但无论哪个版本，COUNT都不应该设置得过大，否则单次HSCAN的执行时间会变长，反而增加了阻塞风险。通常100到1000是比较合理的范围。
从Redis 7.0开始，HSCAN还支持NOVALUES选项，例如 HSCAN key 0 NOVALUES COUNT 500，只返回字段名而不返回值。当只需要检查字段是否存在，或者值本身很大而客户端只关心键名时，NOVALUES可以显著减少网络传输量和内存占用。但要注意，客户端需要根据业务需求决定是否使用该选项，因为遗漏值可能需要额外执行HGET来获取。
实战：在Go和Python中使用HSCAN遍历大哈希
下面是使用Go语言go-redis库遍历哈希的示例。代码中游标类型为uint64，循环条件以返回的cursor是否为0作为结束标志。
package main
import (
"context"
"fmt"
"github.com/go-redis/redis/v8"
)
func main() {
ctx := context.Background()
rdb := redis.NewClient(&redis.Options{
Addr: "127.0.0.1:6379",
})
key := "user:profile"
cursor := uint64(0)
for {
keys, nextCursor, err := rdb.HScan(ctx, key, cursor, "*", 100).Result()
if err != nil {
panic(err)
}
for i := 0; i < len(keys); i += 2 {
field := keys[i]
value := keys[i+1]
fmt.Printf("field=%s value=%s\n", field, value)
}
cursor = nextCursor
if cursor == 0 {
break
}
}
}
Python的redis-py库也提供了hscan方法，返回的游标是整数，数据部分是字典，使用起来更加直观。下面代码展示了如何在Python中完整遍历并处理所有字段。
import redis
r = redis.Redis(host='127.0.0.1', port=6379)
key = 'user:profile'
cursor = 0
while True:
cursor, data = r.hscan(key, cursor=cursor, match='*', count=100)
for field, value in data.items():
print(f'field={field}, value={value}')
if cursor == 0:
break
在实际生产代码中，建议把HSCAN的循环封装成一个生成器或迭代器，方便业务方按需消费。同时要处理Redis连接超时、重试和游标重置等异常情况。如果遍历过程中发生异常，最安全的做法是从0重新开始，并依赖客户端去重来保证最终一致性。
HSCAN与HGETALL、HKEYS的对比及适用场景
HGETALL和HKEYS会一次性返回哈希中的所有字段和值，对小哈希来说非常方便，代码简单且不需要多次网络往返。但当哈希大小达到数万以上时，单次命令执行时间会超过Redis的事件循环时间片，主线程无法处理其他客户端请求，导致整体延迟上升。HSCAN把一次大操作拆分成多次小操作，每次执行时间很短，有效避免了长阻塞。
从网络和CPU开销看，HSCAN需要客户端发起多次请求，总往返次数更多，总耗时可能比一次HGETALL更长。但在高并发系统中，可预测的低延迟比单次请求的绝对速度更重要。此外，HSCAN允许在遍历过程中配合MATCH过滤和COUNT控制批次大小，适合需要分批处理、边遍历边删除或边写入的场景。
总结来说，如果确定哈希键不会超过几百个字段，HGETALL是最简单直接的选择。如果哈希可能增长到数千甚至百万级，并且需要在遍历期间保持Redis对其他请求的响应能力，就应该使用HSCAN。了解两者的取舍，能帮助你在不同业务场景下做出正确决策。
