Python 命令行工具怎么添加子命令

当一个 Python 脚本同时要“列出数据”“创建数据”“删除数据”时，把所有参数堆在同一个 ArgumentParser 里很快就会变得难维护。更清晰的做法是使用 argparse 的子解析器：顶层解析器负责识别命令名，子解析器负责自己的参数，最后把命令映射到对应函数。

先把命令入口拆成可选择的子解析器

假设工具名为 teamctl，现在需要支持 list 和 create。顶层只注册公共信息和子命令集合，不把 --status、--name 这类参数放到顶层。

import argparse


def build_parser():
    # 顶层解析器只描述工具本身和公共帮助信息
    parser = argparse.ArgumentParser(
        prog="teamctl",
        description="管理团队成员的命令行工具",
    )
    # required=True 让用户必须明确选择一个子命令
    subparsers = parser.add_subparsers(
        dest="command",
        required=True,
        title="可用命令",
    )

    # list 只接收自己的筛选参数
    list_parser = subparsers.add_parser("list", help="列出团队成员")
    list_parser.add_argument(
        "--status",
        choices=("active", "paused"),
        default="active",
        help="按成员状态筛选",
    )

    # create 只接收创建成员需要的数据
    create_parser = subparsers.add_parser("create", help="创建团队成员")
    create_parser.add_argument("--name", required=True, help="成员姓名")
    create_parser.add_argument("--email", required=True, help="成员邮箱")
    return parser


if __name__ == "__main__":
    args = build_parser().parse_args()
    print(args)

这里的 dest="command" 会把用户输入的 list 或 create 保存到 Namespace 中，便于日志、测试或后续审计。required=True 是子解析器的关键开关，Python 3.7 起可用；如果需要兼容更旧版本，可以先不设置它，再手动判断 args.command。

让每个子命令绑定自己的参数和处理函数

只完成参数解析还不够，真正可扩展的 CLI 需要让解析结果知道该调用哪个业务函数。最省事的方式是给每个子解析器设置一个 func 默认值。

def handle_list(args):
    # 真实项目中这里可以调用仓储层，而不是在解析器里查数据
    print(f"列出状态为 {args.status} 的成员")


def handle_create(args):
    # 业务函数只消费当前子命令声明过的字段
    print(f"创建成员：{args.name} ")


def build_parser():
    # parser 的构建阶段只注册结构，不执行任何业务副作用
    parser = argparse.ArgumentParser(prog="teamctl")
    subparsers = parser.add_subparsers(dest="command", required=True)

    list_parser = subparsers.add_parser("list", help="列出团队成员")
    list_parser.add_argument("--status", default="active")
    # 把 list 映射到自己的处理函数
    list_parser.set_defaults(func=handle_list)

    create_parser = subparsers.add_parser("create", help="创建团队成员")
    create_parser.add_argument("--name", required=True)
    create_parser.add_argument("--email", required=True)
    # 把 create 映射到自己的处理函数
    create_parser.set_defaults(func=handle_create)
    return parser


args = build_parser().parse_args()
# 子解析器已经选择了处理函数，这里统一派发
args.func(args)

执行 python teamctl.py list --status paused 时，Namespace 中会有 command、status 和 func；执行 create 时则换成 name、email 和同样的 func 入口。没有选中的兄弟子解析器参数不会混入当前 Namespace，这正是子命令能够保持边界的原因。

排查子命令注册后仍然不生效的情况

遇到“明明注册了命令却报错”，先按参数边界检查，而不是马上改业务代码。

调试时可以暂时打印 vars(args) 查看 Namespace 的实际字段。若错误来自拼写，argparse 会在帮助或错误信息中列出可用子命令；不要在每个 handler 里重复判断字符串，这会让注册表和业务逻辑再次耦合。

用统一构建函数让命令持续扩展

命令数量增加后，把所有注册集中在 build_parser()，把处理函数放在独立模块，维护成本最低。新增命令通常只需要三件事：创建子解析器、声明它的参数、绑定 handler。

def build_parser():
    # 统一入口便于单元测试：测试可以直接传入参数列表
    parser = argparse.ArgumentParser(prog="teamctl")
    subparsers = parser.add_subparsers(dest="command", required=True)

    commands = {
        "list": ("列出成员", handle_list),
        "create": ("创建成员", handle_create),
    }
    for name, (help_text, handler) in commands.items():
        # 这里只演示统一绑定；不同命令的专属参数仍应分别声明
        command_parser = subparsers.add_parser(name, help=help_text)
        command_parser.set_defaults(func=handler)
    return parser


parser = build_parser()
# 生产环境通常让 argparse 读取 sys.argv；测试时可传入列表
args = parser.parse_args(["list"])
args.func(args)

这个简化注册表适合命令参数完全一致的场景。若 list 和 create 的参数不同，就保留显式的 add_argument()，不要为了追求循环而把所有字段做成可选项。解析层的目标是尽早拒绝错误输入，业务层的目标才是处理合法数据。

常见问题

子命令一定要设置 dest 吗？

不一定。只需要通过 func 派发时可以不设置；如果日志、测试或条件分支需要知道命令名，建议设置 dest="command"。

可以给所有子命令共享一个参数吗？

可以把公共参数放在顶层解析器，让它出现在命令名前；也可以使用父解析器复用参数定义，但要注意帮助参数冲突。不要把只属于某个子命令的参数放到顶层。

为什么 handler 里拿不到另一个子命令的参数？

这是正常行为。选中的子解析器才会把自己的字段写入 Namespace，兄弟子解析器的参数不会自动存在。共享数据应显式放到顶层参数或公共配置对象中。

用 add_subparsers() 管命令、用子解析器管参数、用 set_defaults() 管派发，Python 命令行工具就能在功能增加时保持清晰边界。最后用总帮助、子命令帮助和一次真实参数调用各检查一遍，通常能很快区分注册问题与业务问题。