Redis COMMAND DOCS 怎么做命令兼容探测：since、arguments 与版本分支

客户端升级后，最容易踩的一个坑是：COMMAND LIST 里扫到了目标命令名，就默认整条调用链已经做好兼容。实际排查中经常会遇到意料外的问题：命令可能来自第三方扩展模块，参数结构也会随版本迭代悄悄改动。Redis 的 COMMAND DOCS、COMMAND INFO 和 COMMAND LIST 分工不同，组合使用才能把“命令存在”和“参数可用”两个校验维度拆开，避免漏判。

先重现命令存在但调用仍失败的场景

把 Redis 版本或客户端库升级后，先做一次最小范围的基础检查：

COMMAND LIST FILTERBY PATTERN "*"
COMMAND INFO SET
COMMAND DOCS SET

三者都能返回命令相关信息，但用途完全不一样。COMMAND LIST 只返回命令名清单；COMMAND INFO 返回一个或多个命令的基本描述，命令不存在时对应返回位置为空；COMMAND DOCS 更偏向文档元数据，能直接看到参数节点和可选分支结构。如果直接把三种返回结果混成一个“是否支持”的布尔值，很容易把兼容问题藏到真正业务调用的时候才暴露出来。

用 COMMAND INFO 做第一层版本门校验

客户端只想快速知道某个命令能不能直接发往服务端，优先用这个方案：

COMMAND INFO HGETDEL
COMMAND INFO UNKNOWN_COMMAND

存在的命令会返回完整描述，不存在的命令对应的返回位置就是空值。这个探测操作不会执行目标命令本身，也不会修改任何业务 key，适合在连接建立后做一次结果缓存。连接池里不要每个请求都做一次探测，不然兼容检查本身会产生不必要的额外流量。

不过，COMMAND INFO 只能回答“服务器认识这个命令名”这一个问题。客户端仍然要自行检查自身的参数编码能力，尤其是新命令带有嵌套参数、重复参数或者模块扩展参数的时候。

用 COMMAND DOCS 看清 arguments 参数树细节

需要自动生成调用器、做参数预校验或者排查版本差异的时候，再去查询完整的文档元数据：

COMMAND DOCS HGETDEL
COMMAND DOCS SET

返回内容会包含命令名、描述、复杂度、ACL 分类、可用版本 since 以及全量参数节点。参数节点可能包含固定标识、参数类型、是否可重复、嵌套的可选分支等信息。这里的重点不是把整段返回结果直接打印到日志，而是提取客户端真正需要的核心字段来做判断。

把四种失败场景拆成不同处理分支

命令不存在

COMMAND INFO 对目标命令返回空，通常意味着服务端版本过低、命令属于未加载的第三方模块，或者当前连接连到了错误的 Redis 实例上。此时不要立刻重试业务命令，先记录 INFO SERVER 的版本和连接地址标识再走后续处理。

命令存在但被 ACL 拒绝

如果命令元数据可以正常读取但实际调用返回权限错误，问题出在授权边界，和版本兼容无关。用管理账号确认命令所属的 ACL 分类，再给应用账号新增最小必要的权限即可。

命令存在但客户端不认识参数树

老旧客户端可能把新参数当作普通字符串处理，也可能在解析数组返回时直接丢失嵌套结构。先保留一份原始 RESP 或者结构化响应的样本，升级客户端解析层之后再放开新命令的调用。

模块命令和内置命令混在一起

COMMAND LIST 的命令名清单不等于核心 Redis 原生能力清单。需要依赖模块能力时，还要额外核对模块加载状态和部署版本，把模块升级流程纳入常规发布检查项。

生产发布前的最小探测脚本

可以在连接池初始化阶段做一次轻量探测，探测结果只缓存到当前进程内即可：

COMMAND INFO HGETDEL
COMMAND DOCS HGETDEL
INFO SERVER

应用侧至少保存三项信息：命令是否存在、since 版本、客户端是否能完整解析 arguments。上线前先用一台对应目标版本的实例跑通全链路验证；回滚时只切换能力开关即可，不要让每个请求都重新做一次兼容判断。

• 把探测逻辑放在进程启动或者连接池建立阶段执行。
• 为“命令不存在”和“权限不足”两种场景定义不同的错误码。
• 日志中记录 Redis 版本、命令名和客户端库版本，不要记录任何敏感业务参数。
• 模块命令单独做一层部署健康检查。

常见问题

COMMAND LIST 能证明命令可以直接调用吗？

不能。它主要返回全量命令名列表，不能证明参数结构、ACL 权限或者客户端解析逻辑都能满足调用要求。

COMMAND INFO 和 COMMAND DOCS 怎么选？

只需要快速判断命令是否存在的时候选 COMMAND INFO；需要获取版本、复杂度和参数树完整信息的时候选 COMMAND DOCS。

COMMAND DOCS 会执行目标命令本身吗？

不会。它只会读取服务端存储的命令元数据，不会修改任何业务 key，但仍建议把它归类为管理探测流量做对应控制。

为什么官方文档里写了有这个命令，线上实例却查不到？

文档可能对应更高的版本或者模块专属能力。先核对实际连接实例的版本、模块加载状态和当前 ACL 用户的权限范围。

兼容探测的边界很清晰：COMMAND INFO 负责存在性校验，COMMAND DOCS 负责提供参数与版本的实际证据，COMMAND LIST 只做全量命令清单展示。把这三层拆开处理，客户端升级的时候才能在真正发起业务调用前给出可解释的分支逻辑。