Redis HSCAN 怎样只返回字段名而不返回值

Redis HSCAN 加上 NOVALUES 就能只返回哈希字段名，省去每个字段对应的值。返回结果仍包含下一游标，但第二部分变成字段名数组，不能继续按字段、值交替配对解析。该选项可用于 Redis 7.4 及支持它的后续版本；部署时也要确认代理和客户端封装支持。

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

把字段清单作为接口目标

假设一个后台接口只要列出配置字段，让使用者决定下一步查看哪一项。普通 HSCAN 会把字段值一起返回，即使应用随后丢弃这些值，传输和解析也已经发生。NOVALUES 适合这种“先列字段、按需读值”的接口。

它不会删除值，也不会把哈希改成集合。只是本次扫描响应省略值。若调用方最终仍要读取每个字段的值，再拆成大量单独读取反而可能增加往返；应先确认接口需求是否真的只要字段名。

使用 NOVALUES 与匹配参数

下面示例使用独立演示键，在本地测试实例准备两个字段。为了让 shell 注释明确有效，命令写成 redis-cli 调用；不包含连接凭据。

# 仅向独立演示键写入示例字段，避免使用业务键。
redis-cli HSET demo:field-list item:title "sample" item:state "ready"
# 游标0表示开始，NOVALUES要求本批只返回字段名。
redis-cli HSCAN demo:field-list 0 NOVALUES
# MATCH匹配字段名；COUNT是扫描工作量提示，不保证返回条数。
redis-cli HSCAN demo:field-list 0 MATCH 'item:*' COUNT 100 NOVALUES

若返回游标不是0，应把原样返回的游标作为下一次调用参数继续扫描。小哈希可能一批就返回全部字段，字段顺序也不构成排序承诺。不要根据这个两字段示例推断大哈希一定一次完成。

业务 API 可把 Redis 响应适配为包含 next_cursor 和 fields 的对象，fields 只保存字段名。游标建议作为不透明字符串传递，不把它当页码，也不根据数值大小推算完成比例。

调整客户端返回结构

现有封装若固定每两个元素组成一个键值对，加上 NOVALUES 后就可能错误吞掉一半字段，或因数组长度为奇数而报错。正确适配是按字段数组处理；调用参数和解析器必须同步改变。

如果客户端已有字段专用扫描接口，应按其文档使用；若只能发原生命令，就选择能保留原始数组结构的返回类型。不要假定所有版本的客户端都能在普通 HSCAN 方法后追加一个字符串而保持原有返回类型。

处理游标和错误

整轮迭代从0开始，直到服务器返回0结束。MATCH 可能使某批字段数组为空，只要游标尚未归零就还没结束。COUNT 不是分页大小，NOVALUES 也不会把 HSCAN 变成快照分页。

持续修改的哈希可能使扫描结果包含重复字段；需要唯一字段清单时在调用方去重。若数据集合在迭代期间变化，不能把结果描述为某个时刻严格一致的完整快照。重试、去重和取消策略应由接口明确承担。

报语法错误时先核对选项支持，报 WRONGTYPE 时核对键类型，权限拒绝时核对账号权限。不要把所有失败都降级成“空字段列表”，否则调用方无法区分没有字段与扫描失败。

制定旧版本兼容与调用示例

旧服务端不支持 NOVALUES 时，可回退普通 HSCAN，再在应用端提取每对元素的字段名。这保留了游标扫描方式，但不会节省值的网络传输。若哈希大小可控并且允许单次获取全部字段，HKEYS 是另一种选择；它没有扫描游标，不能无条件替代大哈希上的逐批处理。

混合版本部署应在发布配置或能力信息中明确采用哪条路径，避免每一批都先触发语法错误再盲目重试。服务端能执行原生命令、代理能转发选项、客户端能解析字段数组，是三个分别需要满足的条件。

演示结束后，可只清理演示键：

# 仅删除本例创建的独立演示键，不对业务哈希执行清理。
redis-cli DEL demo:field-list

NOVALUES 会自动去重或排序吗？不会。它只控制是否携带值，迭代顺序和重复处理仍遵循扫描语义。

MATCH 会匹配值内容吗？不会，HSCAN 的模式针对哈希字段名。按值筛选是另一项业务需求，不能靠 NOVALUES 完成。

COUNT 100 是否必须得到100个字段？不是。它是工作量提示，可能返回更少、为空或对小编码集合一次返回全部字段。

字段清单接口使用 NOVALUES 时，最关键的配套改变是把客户端第二部分解析为字段数组，再把游标结束条件与兼容回退写清楚。

参考：Redis HSCAN 命令；SCAN 迭代语义；Redis 7.4 HSCAN 参数与响应定义。