Go flag.FlagSet 如何嵌入子命令：错误处理、Usage 输出与参数隔离

一个命令行工具开始只有 -config 和 -verbose 两个参数，过一阵子就会长出 start、stop、check 三条操作路径。继续把所有参数注册到全局 flag.CommandLine，最容易出现的结果是：用户执行 stop -pid 8 时，启动参数也混在帮助信息里，错误分支还可能直接退出进程。

把每个子命令放进自己的 flag.FlagSet，再用 ContinueOnError 接住解析错误，通常就能同时解决参数串线、测试难写和 Usage 无法按命令定制这三个问题。

先看全局 flag 为什么会让子命令变脆

全局集合适合单层参数，例如 tool -config app.yaml -verbose。一旦命令语法变成 tool start -addr :8080，全局集合就不得不同时认识不同动作的参数。这样不仅帮助信息变长，参数名重复时还会发生注册冲突。

更隐蔽的问题是错误处理。默认的 flag.CommandLine 使用 ExitOnError，遇到未知参数会结束当前进程。对一次性 CLI 也许够用，但在单元测试或需要统一返回码的服务包装器中，直接退出会截断清理和断言。

用 NewFlagSet 建立参数隔离

下面的最小示例只保留 start 和 stop。关键顺序是：先判断第一个位置参数，再为它选择独立集合；不要先用一个集合把整行参数吃掉。

package main

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

func newStartSet(out io.Writer) (*flag.FlagSet, *string) {
    fs := flag.NewFlagSet("start", flag.ContinueOnError)
    fs.SetOutput(out)
    addr := fs.String("addr", ":8080", "监听地址")
    fs.Usage = func() {
        fmt.Fprintln(out, "用法: tool start [-addr 地址]")
        fs.PrintDefaults()
    }
    return fs, addr
}

func newStopSet(out io.Writer) (*flag.FlagSet, *int) {
    fs := flag.NewFlagSet("stop", flag.ContinueOnError)
    fs.SetOutput(out)
    pid := fs.Int("pid", 0, "要停止的进程号")
    fs.Usage = func() {
        fmt.Fprintln(out, "用法: tool stop -pid 进程号")
        fs.PrintDefaults()
    }
    return fs, pid
}

func main() {
    if len(os.Args) 

这里的 addr 只属于 start，pid 只属于 stop。运行 tool start -pid 8 时，start 集合会报告未知参数；这比把它误当作启动配置更容易定位。

ContinueOnError 怎样把失败交还给调用方

flag.ContinueOnError 不代表忽略错误，而是让 Parse 把错误返回出来。调用方可以决定是打印 Usage、返回自定义退出码，还是交给上层测试。

func parseStart(args []string) (string, error) {
    fs := flag.NewFlagSet("start", flag.ContinueOnError)
    fs.SetOutput(io.Discard)
    addr := fs.String("addr", ":8080", "监听地址")
    if err := fs.Parse(args); err != nil {
        return "", fmt.Errorf("解析 start 参数: %w", err)
    }
    return *addr, nil
}

addr, err := parseStart([]string{"-unknown", "x"})
fmt.Println(addr, err != nil) //  输出:  true

测试时把输出写入 bytes.Buffer 更直观：断言错误非空，检查输出是否包含 flag provided but not defined，而不是让测试进程因为默认退出策略提前结束。

Usage 和输出目标要一起设置

每个 FlagSet 都有自己的 Usage 函数。自定义时要关闭对全局标准错误的隐式依赖，使用 SetOutput 把帮助和错误导向调用者提供的 writer。这样同一套解析函数既能服务终端，也能服务测试。

var buf bytes.Buffer
fs := flag.NewFlagSet("check", flag.ContinueOnError)
fs.SetOutput(&buf)
fs.Usage = func() {
    fmt.Fprintln(fs.Output(), "用法: tool check -file 路径")
}
_ = fs.Parse([]string{"-h"})
// buf 中应包含 check，而不是 start 或 stop 的参数。

四个容易误判的边界

位置参数从哪里开始

FlagSet 遇到第一个非 flag 参数后会停止继续解析。子命令路由应在外层完成，子命令参数则完整传给对应的 Parse；不要把后半段误认为仍是全局选项。

-h 是错误吗

帮助请求会触发 Usage，并返回 flag.ErrHelp。调用方应把它当作正常帮助分支处理，而不是显示成业务失败。

默认值在哪里读取

String、Int 等方法返回指针，解析成功后读取指针值。若需要区分“用户没有传”和“用户显式传了默认值”，应额外记录是否出现该参数。

多个集合能否复用

不建议把已解析的集合拿来处理下一次请求。命令行参数解析通常是一次性的；需要重复测试时，每个测试新建 FlagSet，避免残留状态影响结果。

用三组命令做最终核对

1. tool start -addr :9090：输出启动地址，且不出现 -pid。
2. tool stop -pid 8：输出待停止进程号，且不出现 -addr。
3. tool start -unknown x：返回错误并显示 start 的帮助，不直接结束测试宿主。

如果工具还需要全局参数，可以把它们限制在子命令名之前，例如先解析 tool -config app.yaml start -addr :9090 的全局前缀，再把剩余切片交给 start 的 FlagSet。边界一旦固定，参数归属和错误码就都能写成测试。

相关问题

FlagSet 能完全替代第三方命令行库吗？

如果只需要短选项、默认值和子命令隔离，标准库通常够用；需要嵌套命令、复杂补全或更丰富的参数类型时，再评估第三方库。

生产命令应该使用 ExitOnError 吗？

顶层一次性命令可以使用它，但可复用解析函数和测试代码更适合 ContinueOnError，把退出决策留在最外层。

为什么不能所有参数都注册到 CommandLine？

全局集合没有表达子命令边界，容易造成帮助混杂、名字冲突和错误处理不可控。FlagSet 的价值正是把这些状态分开。

小结

子命令 CLI 的核心不是多写几个 switch，而是让每条命令拥有自己的参数集合、输出目标和错误策略。先路由，再解析；先处理 ErrHelp 和普通错误，再执行动作。用这三个检查点约束代码，后续增加 config 或 check 时，原有 start、stop 的参数不会互相污染。