Redis 8.10 命令文档怎样帮助客户端做能力探测

Redis 8.10 的命令参考可以告诉客户端“这一版本有哪些命令、参数和历史变化”，但它不能替代对目标实例的运行时探测。客户端真正要做的是：连接目标 Redis，读取版本和命令元数据，把结果整理成能力表，再决定调用 Redis 8.10 新命令、保留旧路径，还是安全降级。

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

最小可靠方案是把版本文档当作设计依据，把 INFO、COMMAND DOCS 和 COMMAND INFO 的响应当作目标连接的事实依据。命令不存在、不可见、无权限和响应未知，应该分开记录，不能都当成“版本太旧”。

先把“文档能力”和“实例能力”分开

Redis 官方命令目录当前提供 Redis 8.10 的版本化参考，并在命令条目中标出命令摘要、语法、复杂度和引入版本。例如 Redis 8.10 的参考页列出了 HIMPORT、BACKUP、LMOVEM、SUNIONCARD 等新增或扩展能力。它适合用来设计客户端，但页面本身并不知道你的连接实际连到了哪个节点，也不知道当前账号是否能执行某条命令。

运行时至少存在三层事实：

• 版本事实：INFO server 的 redis_version 可以帮助记录服务端版本，但不能单独决定某个命令一定可执行。
• 命令元数据：COMMAND DOCS 返回摘要、since、分组、复杂度、历史和参数描述；COMMAND INFO 更适合读取命令标志、键位置和访问属性。
• 权限和拓扑事实：ACL、模块加载状态、集群节点差异和代理行为，都可能让“文档中存在”的命令在当前连接上不可用。

先用 INFO 记录连接看到的版本

INFO server 适合写入连接诊断信息。官方文档也提醒，INFO 字段可能随 Redis 版本增加或删除，健壮客户端要跳过未知字段并容忍缺失字段。因此它更适合作为日志和初步分支条件，不能代替命令元数据探测。

# 只读取服务端区段，避免把无关统计一起拉回来
redis-cli -h 127.0.0.1 -p 6379 INFO server

# 仅提取版本字段；没有匹配项时不要把它当成 Redis 旧版本
redis-cli -h 127.0.0.1 -p 6379 INFO server | awk -F: '$1 == "redis_version" {print $2}'

如果返回的版本是 8.10.x，可以把它记录为“版本上可能支持”的线索；如果是代理、云服务或模块化发行版，仍然应该继续询问命令元数据。版本字符串为空、格式异常或 INFO 被 ACL 拒绝时，也不能直接把全部新能力标记为不可用。

用 COMMAND DOCS 询问具体命令

COMMAND DOCS 从 Redis 7.0 开始提供，默认可以返回全部命令的文档信息，也可以只指定一个或多个命令。能力探测不需要每次拉取全量目录，通常只询问业务真正可能使用的命令，例如 HIMPORT、BACKUP 和 SUNIONCARD。

# 按业务候选集合读取文档元数据，减少响应体和解析成本
redis-cli --raw COMMAND DOCS HIMPORT BACKUP SUNIONCARD

# 只探测新路径；返回 nil 或缺少命令键时，进入兼容分支
redis-cli --raw COMMAND DOCS HIMPORT

客户端重点看四类字段：

• since：命令或模块命令从哪个版本开始提供，可用于解释为什么选择某条路径。
• arguments：参数名称、类型、可选标志和嵌套关系，可用于提前决定是否能组装调用。
• history：参数或返回结构的历史变化，提醒客户端不要只按命令名判断兼容性。
• doc_flags：例如弃用或系统命令标记，便于阻止新代码继续依赖不合适的入口。

这里的“存在”不是“可以放心调用”。命令元数据可见，说明服务器愿意描述它；实际调用仍可能因为 ACL、模块权限、只读副本或参数不被当前版本接受而失败。

COMMAND INFO 适合做轻量级分支

如果客户端只关心命令是否存在、读写属性、ACL 分类、第一键和最后键等信息，可以使用 COMMAND INFO。它的返回结构比完整文档更适合作为连接初始化时的轻量缓存。

# 同时读取命令标志和键规格相关元数据
redis-cli --raw COMMAND INFO HIMPORT XREADGROUP SORT

# 命令不存在时，保留“不可见”状态，不把空响应改写成默认可用
redis-cli --raw COMMAND INFO HIMPORT | sed -n '1,40p'

在客户端中，可以把能力拆成三种判断：

集群客户端还要理解 key specifications

能力探测不只是“命令名能不能执行”。集群客户端还要知道命令涉及哪些键，才能把请求路由到正确的分片。Redis 的 COMMAND 元数据包含 ACL 分类、键规格和子命令信息；对于带有 movablekeys 标志的命令，第一键、最后键和步长不足以完整找出键位置。

官方文档列出的典型边界包括 SORT、ZUNION 和 MIGRATE。Redis 7.0 起，客户端可以使用 key specifications；对仍需要解析实际调用参数的 SORT 和 MIGRATE，才考虑 COMMAND GETKEYS。因此，缓存命令能力时最好同时保存：

• 命令是否存在以及是否可读、可写；
• 键规格、第一键、最后键、步长和 movablekeys；
• 目标节点或代理的身份；
• 探测时间、响应错误类型和缓存过期时间。

这样做可以避免一种常见误判：客户端发现命令存在，于是直接发送多键请求，但没有按键规格路由，最后得到的是跨槽错误，而不是版本不支持。

把探测结果变成可回退的能力表

简明的能力表不必记录整份官方文档。对每个业务能力保存命令名、最低版本线索、是否可见、参数指纹、权限结果和回退动作即可。例如业务需要批量处理集合基数时，可把 SUNIONCARD 记为新路径，把先计算集合再统计的旧逻辑记为回退路径。

# 这是能力表的示意字段，不是 Redis 返回的固定 JSON 格式
capability: set-cardinality
preferred_command: SUNIONCARD
fallback: read-and-count
state: available | hidden | denied | unknown
node_scope: connection-or-node
expires_after: short-ttl

实际代码中不要只保存布尔值。至少区分以下状态：

• available：元数据可见，且一次低成本的权限/参数检查通过。
• hidden：服务器没有返回该命令，可能是旧版本、模块未加载或代理裁剪。
• denied：命令存在，但当前账号不能访问；此时不应不断重试同一条命令。
• unknown：网络超时、响应不完整或解析器不认识返回结构，暂时不要把它写成不可用。

四个容易误判的边界

1. 版本号不等于能力。版本可以是 8.10，但命令可能被代理隐藏、被模块状态影响，或当前连接不是实际执行节点。
2. 文档可见不等于权限通过。COMMAND DOCS 能描述命令，不代表当前 ACL 用户可以执行它。
3. 空结果不等于旧版本。空结果还可能来自模块没有加载、代理白名单或响应解析错误，应该保留原因字段。
4. 探测结果不应永久缓存。集群滚动升级、主从切换和模块变更都会让能力状态发生变化，缓存需要绑定节点并设置过期时间。

一份可落地的最小检查清单

如果要把这套机制放进客户端初始化，可以按下面的顺序收敛范围：

1. 连接建立后读取 INFO server，只记录版本线索，不直接决定功能开关。
2. 根据业务候选集请求 COMMAND DOCS，需要轻量路由信息时补充 COMMAND INFO。
3. 为每个命令记录可见、无权限、未知等状态，并保留原始错误类别。
4. 集群模式额外读取 key specifications 和 movablekeys 相关信息。
5. 把新命令与旧路径绑定成一个能力，而不是把调用点散落在业务代码里。
6. 滚动升级、切换节点或收到未知命令错误时，让能力缓存失效并重新探测。

这样，Redis 8.10 的版本文档就从“查新命令的网页”变成了客户端设计输入，而运行时命令元数据负责回答“当前这条连接到底能不能走这条路径”。

相关问题

COMMAND DOCS 会返回哪些内容？

官方文档列出的返回映射可能包含摘要、引入版本、功能分组、复杂度、文档标志、弃用信息、历史记录和参数描述。客户端应允许字段增减。

只读取 redis_version 能判断 Redis 8.10 新命令吗？

不能。版本号只能提供初步线索，最终还要结合目标连接返回的命令元数据、模块状态、权限和拓扑。

为什么探测到命令后仍然会得到权限错误？

命令元数据的可见性与执行权限是两件事。ACL 可能允许读取描述，却不允许执行命令；这时应记录为 denied 并走安全降级。