Go 命令行工具怎么实现子命令和独立参数

当一个 Go 命令行程序从单个 -config 参数扩展到 serve、check 等子命令时，最容易出问题的不是参数数量，而是解析责任混在一起。实用做法是：主程序只读取 os.Args[1] 选择子命令，每个子命令各自创建一个 flag.FlagSet，再对 Parse 后留下的位置参数做业务校验。

子命令的独立性来自独立的 FlagSet，而不是给全局 flag 起更多名字。这样 serve -port 8080 和 check -format json 的帮助、默认值、错误和参数集合才不会互相污染。

先把命令名和参数解析责任分开

把整个 os.Args 交给一个全局 FlagSet，短期看代码少，后续却很难判断某个参数属于哪个命令。更稳的分层是命令入口、命令分发和子命令解析：入口只验证是否提供命令名，分发层只决定调用哪个函数，参数层才定义 -port、-config 或 -format。

这种拆分还有一个安全收益：未知子命令在进入业务逻辑前就被拒绝；未知参数也只会影响当前子命令，不会被另一套默认值“接住”。命令名属于路由输入，参数属于子命令输入，两者不要共用一组可变状态。

用独立 FlagSet 保存子命令参数

下面的示例让 serve 与 check 使用完全不同的参数集合。FlagSet.Parse 接收的是子命令之后的切片，因此主程序不需要修改全局 flag.CommandLine。

package main

import (
    "flag"
    "fmt"
    "os"
)

func main() {
    if len(os.Args)  [flags]")
        os.Exit(2)
    }
    var code int
    switch os.Args[1] {
    case "serve":
        code = runServe(os.Args[2:])
    case "check":
        code = runCheck(os.Args[2:])
    default:
        fmt.Fprintf(os.Stderr, "unknown command: %s\n", os.Args[1])
        code = 2
    }
    os.Exit(code)
}

func runServe(args []string) int {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    port := fs.Int("port", 8080, "listen port")
    config := fs.String("config", "app.yaml", "config file")
    if err := fs.Parse(args); err != nil { return 2 }
    if fs.NArg() != 0 || *port  65535 {
        fmt.Fprintln(os.Stderr, "serve: invalid flags or extra arguments")
        return 2
    }
    fmt.Printf("serve config=%s port=%d\n", *config, *port)
    return 0
}

func runCheck(args []string) int {
    fs := flag.NewFlagSet("check", flag.ContinueOnError)
    format := fs.String("format", "text", "text or json")
    if err := fs.Parse(args); err != nil { return 2 }
    paths := fs.Args()
    if len(paths) == 0 || (*format != "text" && *format != "json") {
        fmt.Fprintln(os.Stderr, "check: provide a path and a valid format")
        return 2
    }
    fmt.Printf("check format=%s paths=%v\n", *format, paths)
    return 0
}

图中的 serve FlagSet 和 check FlagSet 是两个独立对象。它们可以有同名参数而互不冲突；更重要的是，处理函数只接收属于自己的 args，测试时也能直接传入切片，不必改写进程级参数。

在 Parse 之后读取位置参数并校验

标准库把选项和位置参数分开处理。Parse 成功后，fs.Args() 返回未被识别为 flag 的参数，fs.Arg(0) 可以读取其中某一项，fs.NArg() 返回数量。不要把“解析成功”误当成“业务输入合法”：check 至少要要求一个路径，serve 则应拒绝多余路径。

官方 flag 规则允许单横线或双横线形式；解析会在第一个非 flag 参数前停止，也会在 -- 后停止。布尔参数不能用单独的下一个词关闭，关闭时使用 -verbose=false 更明确。若命令需要“选项可以出现在位置参数之后”，标准库 FlagSet 并不提供这种重新扫描语义，应在命令设计阶段明确限制，或改用更适合该语法的解析器。

把帮助、错误与审计边界固定下来

示例使用 flag.ContinueOnError，让处理函数拿到解析错误并返回退出码，而不是在库内部直接结束进程。生产命令还可以调用 fs.SetOutput 把帮助和错误统一送到指定 writer；图中 ContinueOnError、SetOutput、Parse、业务校验、拒绝原因 和 结果报告 构成一条可追踪的静态控制链。

建议把失败分成三类：未知命令属于分发失败，未知 flag 或类型转换失败属于解析失败，端口越界或路径缺失属于业务校验失败。三类错误都返回非零状态，但提示语应包含当前命令名，避免用户把 check 的错误误认为 serve 的参数问题。需要审计时记录命令名、参数校验结果和拒绝原因即可，不要把密钥或完整敏感参数写进日志。

落地前可以按这份清单复核：每个子命令是否有自己的 FlagSet；是否只把 os.Args[2:] 传给它；Parse 后是否检查 NArg；是否定义未知命令与错误退出码；帮助输出是否能说明当前命令的参数。

常见问题

为什么不直接复用全局 flag.CommandLine？

全局集合适合单层命令。子命令一多，参数定义和解析状态会共享，帮助文本也难以按命令隔离。独立 FlagSet 更容易测试和维护。

FlagSet.Parse 成功但程序仍应报错，为什么？

Parse 只说明选项格式能被解析，不代表业务条件满足。位置参数数量、端口范围、文件存在性等规则要在 Parse 之后自行判断。

如何让布尔参数关闭？

使用 -verbose=false 或 --verbose=false。布尔 flag 后面紧跟普通单词不会被当成它的关闭值。

-- 有什么作用？

它是选项终止符；后面的内容会留在 Args() 中，适合把以连字符开头的文件名或业务字符串当作位置参数处理。