Redis COMMAND DOCS 怎样取得参数结构与版本说明

在做 Redis 客户端、命令补全或多版本兼容层时，只记住命令名远远不够：还要知道参数有哪些分支、哪些选项是可选的，以及这些字段从哪个 Redis 版本开始出现。COMMAND DOCS 专门返回面向文档的命令元数据，可以按命令名查询，也可以一次取得整台服务器的命令说明。

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

最实用的用法是先按需查询一个或几个命令，再把顶层字段与递归的 arguments 分开处理；since 说明命令或参数的版本起点，history 记录输出或参数结构的历史变化。

先按负载选择查询范围

COMMAND DOCS 在 Redis Open Source 7.0.0 中加入，语法是 COMMAND DOCS [command-name ...]。不带命令名时返回服务器支持的全部命令；带一个或多个命令名时，只返回指定命令。官方给出的复杂度是查询命令数的 O(N)，所以客户端初始化时不应该为了展示一个命令而无条件拉取全量目录。

# 只拿一个命令，适合补全或帮助面板按需加载
redis-cli COMMAND DOCS SET

# 一次拿多个命令，适合初始化一组固定能力
redis-cli COMMAND DOCS GET SET EXPIRE

# 全量目录，适合离线建立命令索引；线上请求要评估返回体大小
redis-cli COMMAND DOCS

这里的命令名不必拘泥于大写，Redis 命令名本身不区分大小写。工程上可以把用户输入统一转成大写作为缓存键，但不要把“查不到文档”和“命令不存在”混成同一个异常：客户端还应保留空结果与传输错误的区别。

顶层字段回答了什么问题

以 COMMAND DOCS SET 为例，返回结果的第一层通常以命令名作为键，值是该命令的文档映射。先处理顶层字段，能得到一条足够稳定的摘要：

因此，适合保存的内部对象可以拆成“摘要”和“语法树”两部分。摘要用来搜索与展示，语法树用来生成补全、校验输入或渲染参数说明，避免把一大段 RESP 返回直接塞进前端。

递归读取 arguments 才能还原参数结构

参数数组中的每一项通常由 name、type、display_text、token、since、flags 和嵌套的 arguments 组成。简单参数可以直接展示；oneof 表示分支选择，block 表示一组嵌套参数，optional 与 multiple 则影响输入数量。

def flatten_arguments(items, parent=None):
    # 把 Redis 的参数树转成适合搜索和补全的扁平记录
    rows = []
    for item in items or []:
        name = item.get("name", "")
        row = {
            "name": name,
            "type": item.get("type", ""),
            "token": item.get("token"),
            "flags": item.get("flags", []),
            "since": item.get("since"),
            "parent": parent,
        }
        rows.append(row)
        # oneof、block 等节点会把真正的选项放在 arguments 中
        rows.extend(flatten_arguments(item.get("arguments"), name))
    return rows

这个转换只改变存储形状，不改变 Redis 的语义。渲染时仍要保留父子关系：例如 condition 下的 NX、XX 是同一组选项，不能因为扁平化就让它们看起来可以同时出现。

用 since 和 history 处理版本边界

since 是最直接的兼容判断：命令级 since 说明命令首次出现的版本，参数节点上的 since 则说明该参数从哪个版本起可用。history 是历史条目数组，每条记录包含版本和变化描述，重点用于解释输出格式或参数结构的演进。

这意味着兼容层可以采用两级策略：先判断服务端版本是否达到命令级起点，再在生成参数建议时过滤高于目标版本的参数节点。不要仅凭 history 推断业务行为变化，也不要把当前文档页面的完整命令列表当成所有旧版本都具备的能力。

COMMAND DOCS 和 COMMAND INFO 怎么分工

两者都能拿到命令元数据，但目标不同。COMMAND DOCS 面向文档，字段更适合解释参数、版本和帮助文本；COMMAND INFO 面向服务器当前能处理的命令信息，常用于了解 arity、flags、key 位置和 key specification。需要生成用户帮助时优先 DOCS，需要做集群路由或运行时能力判断时再看 INFO。

一个稳妥的落地清单是：

• 按需查询时传入具体命令名，避免无目的全量拉取。
• 把 arguments 当树处理，保留 oneof、block、optional 和 multiple 语义。
• 把命令级与参数级 since 分开存储，并把 history 当变更说明展示。
• 需要集群键路由时补充 COMMAND INFO，不要用文档摘要替代 key specification。

常见问题

COMMAND DOCS 不带参数会不会返回所有命令？

会。官方文档说明省略命令名时默认返回服务器的全部命令；只查一个命令时应明确传入命令名。

为什么只读取 arguments 第一层会漏掉选项？

因为可选分支和参数块可能继续嵌套在子级 arguments 中。应递归遍历，并在展示或补全时保留父节点关系。

COMMAND DOCS 能替代 COMMAND INFO 吗？

不能完全替代。前者偏文档和参数解释，后者偏运行时命令能力、键位置与路由信息，使用场景不同。

总结

要取得 Redis 命令的参数结构与版本说明，可以把 COMMAND DOCS 看成“命令文档映射”：先用命令名控制查询范围，再读取顶层摘要，最后递归展开 arguments。用 since 做兼容边界，用 history 解释结构演进；当任务转向集群路由和运行时键信息时，再切换到 COMMAND INFO。