Go flag.FlagSet 写子命令：参数解析、Usage 与错误退出码

命令行工具刚开始只有一个 --config 参数时，直接用 flag.String 和 flag.Parse() 写功能非常省心。等到同一个程序多出 serve、migrate、version 三个入口，最先碰到的往往是边界问题：子命令各自的参数该由谁解析，出错时该打印哪一份 Usage 说明，以及执行失败最终要返回什么退出码。

每个子命令都使用独立的 flag.FlagSet，把参数定义、帮助输出和业务调用分开；解析失败直接由该子命令处理，主入口只负责选择命令和统一退出。

从一个参数入口开始，问题在哪里暴露

先看大家最容易随手写出的简单版本：

var config = flag.String("config", "app.yaml", "配置文件")

func main() {
    flag.Parse()
    fmt.Println("serve with", *config)
}

这个版本本身没有语法错误。麻烦的是新增 migrate 后，--config、--dry-run 和 --table 会被迫共享一组全局参数定义。用户输入 tool migrate --table users 时，默认解析器根本不知道“migrate”是一个子命令，参数归属完全没有清晰的边界。

这里完全不用急着引入第三方库。标准库的 flag.FlagSet 已经能把这三个职责完全切开。

用 flag.FlagSet 给每个子命令划边界

入口先只读取第一个位置参数，后面剩余的参数直接交给对应的 FlagSet 处理：

func main() {
    code := run(os.Args[1:])
    os.Exit(code)
}

func run(args []string) int {
    if len(args) == 0 {
        printRootUsage()
        return 2
    }

    switch args[0] {
    case "serve":
        return runServe(args[1:])
    case "migrate":
        return runMigrate(args[1:])
    case "help", "-h", "--help":
        printRootUsage()
        return 0
    default:
        fmt.Fprintf(os.Stderr, "unknown command: %s\n", args[0])
        printRootUsage()
        return 2
    }
}

run 不需要创建服务、不需要连接数据库，它只做子命令路由。这样在写单元测试的时候，可以直接传入一组字符串，检查返回码是否符合预期，完全不需要真的启动新进程。

ContinueOnError 让 Usage 和错误回到调用方

子命令的参数定义可以参考这样的写法：

func runServe(args []string) int {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    fs.SetOutput(os.Stderr)

    addr := fs.String("addr", ":8080", "监听地址")
    config := fs.String("config", "app.yaml", "配置文件")
    if err := fs.Parse(args); err != nil {
        return 2
    }
    if fs.NArg() != 0 {
        fmt.Fprintln(os.Stderr, "serve 不接受额外位置参数")
        fs.Usage()
        return 2
    }

    fmt.Printf("start server addr=%s config=%s\n", *addr, *config)
    return 0
}

ContinueOnError 不会在解析失败时直接终止整个进程，而是把错误返回给上层 runServe。SetOutput 则能避免测试或上层调用时，错误信息偷偷输出到默认输出流，没被代码捕获。

输入 tool serve --addr :9000 时，addr 属于 serve；输入未知选项时，也只会弹出 serve 对应的 Usage 说明。这个范围比共用默认 FlagSet 清晰得多，用户读帮助信息时也不会被无关选项干扰。

帮助信息不要和业务逻辑搅在一起

根命令和子命令是两层帮助体系。根命令先告诉用户当前程序提供了哪些入口，子命令的 -h 负责展示自己对应的全部选项：

func printRootUsage() {
    fmt.Fprintln(os.Stderr, "用法: tool  [options]")
    fmt.Fprintln(os.Stderr, "命令:")
    fmt.Fprintln(os.Stderr, "  serve       启动 HTTP 服务")
    fmt.Fprintln(os.Stderr, "  migrate     执行数据库迁移")
    fmt.Fprintln(os.Stderr, "  version     显示版本")
}

如果 fs.Parse 遇到 -h，flag 会调用当前 FlagSet 的 Usage 并返回 flag.ErrHelp。通常我们可以把它当作正常的帮助请求处理即可：

if err := fs.Parse(args); err != nil {
    if errors.Is(err, flag.ErrHelp) {
        return 0
    }
    return 2
}

帮助内容写向标准输出还是标准错误，可以按自己工具的使用习惯决定，但同一个程序内要保持一致。自动化脚本一般只关心退出码和对应输出流，不要让两者的规则互相矛盾，导致脚本判断逻辑出错。

migrate 的位置参数和错误码验收

另一个子命令可以要求用户恰好传入一个迁移文件夹路径：

func runMigrate(args []string) int {
    fs := flag.NewFlagSet("migrate", flag.ContinueOnError)
    fs.SetOutput(os.Stderr)
    dryRun := fs.Bool("dry-run", false, "只检查，不写入")
    if err := fs.Parse(args); err != nil {
        return 2
    }
    if fs.NArg() != 1 {
        fmt.Fprintln(os.Stderr, "用法: tool migrate [--dry-run] ")
        return 2
    }

    fmt.Printf("migrate dir=%s dry-run=%t\n", fs.Arg(0), *dryRun)
    return 0
}

验收功能的时候不要只看屏幕上“看起来像是成功”。至少要覆盖四类输入场景：无命令返回 2，未知命令返回 2，serve -h 返回 0，migrate --dry-run ./db 返回 0。错误码稳定之后，Shell 脚本、CI 流程和上层调用工具才有可靠的判断依据。

几个容易踩到的边界

不要把子命令名留在 FlagSet 参数里

传给 runServe 的应该是 args[1:]，而不是整组原始输入参数。否则 FlagSet 会把 serve 当成普通位置参数处理，后续的 fs.NArg() 校验就会出现误判。

不要在业务函数里调用 os.Exit

os.Exit 会让测试流程直接中断，也会跳过预定义的延迟清理逻辑。让 runServe 和 runMigrate 直接返回整数状态码，最后由 main 统一执行退出操作，职责边界会更清晰。

参数解析成功不等于业务执行成功

路径存在、配置可读、数据库连接可用，这些都是参数解析之后才需要做的检查。参数层只负责校验参数的格式和类型是否合法，业务层再返回对应场景的错误，别把所有失败都笼统归类成“unknown flag”。

相关问题

一个 Go 程序有多个子命令，必须使用第三方库吗？

不必须。子命令数量不多、参数类型简单时，多个 flag.FlagSet 已经足够用；需要自动补全、多层嵌套命令或者复杂的帮助排版时，再去评估专用第三方库就好。

flag.FlagSet 能否复用？

可以复用参数定义的函数，但不建议在多次调用之间复用同一个 FlagSet 实例。每次执行命令调用时创建新的 FlagSet，状态更容易完全隔离，不会出现互相串值的问题。

为什么错误退出码常用 2？

这里把 0 留给正常执行和帮助展示场景，把 2 作为参数或命令用法错误的统一返回码。重点不是数字本身，而是整个项目内保持规则稳定，同时在测试和文档里写清楚对应含义就好。

收尾：把命令行入口当成一层适配器

flag.FlagSet 的价值不在于替代所有 CLI 框架，而在于让每个子命令拥有自己独立的参数表、Usage 和解析结果。主入口负责选择子命令，子命令负责校验参数，业务函数负责真正的执行逻辑，最后由最外层统一处理退出码。这个拆分改动量很小，却能让参数串台、帮助信息混乱和测试难写这三类常见问题同时收敛。