Go flag 怎样为子命令分别生成帮助信息

用 Go 的 flag 包写多子命令工具时，最容易遇到的现象是：执行 tool serve -h，帮助里却混进了 config 的参数；或者所有子命令共用一套 Usage，读者不知道当前参数属于哪条命令。解决办法不是继续拼接字符串，而是让每个子命令拥有自己的 flag.FlagSet，再分别设置 Usage。

官方地址：https://pkg.go.dev/flag

根命令只负责识别子命令，子命令再用独立 FlagSet 解析自己的参数。帮助请求、参数错误和默认值说明，都由这套 FlagSet 的 Usage 统一输出。

先把帮助输出拆成两层

多子命令程序可以看成两次选择：第一次从 os.Args 中取出 serve 或 config，第二次把剩余参数交给对应的 FlagSet。根命令不要把两个子命令的参数都注册到全局 flag.CommandLine，否则帮助范围天然混在一起。

一个适合排查的最小模型是：

根命令：识别子命令
    ├── serve：创建 serve FlagSet，设置 -port
    └── config：创建 config FlagSet，设置 -file

这样设计后，serve 的 Usage 只描述端口和服务启动方式，config 的 Usage 只描述配置文件，不需要在输出阶段再猜测参数归属。

为每个子命令创建自己的 FlagSet

flag.NewFlagSet 接收一个名称和错误处理策略。多子命令场景通常使用 flag.ContinueOnError，这样 Parse 出错时由当前函数决定是否打印 Usage 和返回错误，不会因为一个子命令参数写错就直接结束整个进程。

package main

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

func newServeCommand(out io.Writer) *flag.FlagSet {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    // 把帮助和错误输出集中到调用方，便于测试和统一日志出口。
    fs.SetOutput(out)
    fs.Usage = func() {
        fmt.Fprintln(out, "用法：tool serve [选项]")
        fs.PrintDefaults()
    }
    // 这里只注册 serve 自己的参数，不共享根命令的 FlagSet。
    fs.Int("port", 8080, "监听端口")
    fs.Bool("verbose", false, "输出详细日志")
    return fs
}

func newConfigCommand(out io.Writer) *flag.FlagSet {
    fs := flag.NewFlagSet("config", flag.ContinueOnError)
    // 每个子命令都有自己的标题和参数说明。
    fs.SetOutput(out)
    fs.Usage = func() {
        fmt.Fprintln(out, "用法：tool config [选项]")
        fs.PrintDefaults()
    }
    fs.String("file", "app.yaml", "配置文件路径")
    fs.Bool("check", false, "只检查配置，不启动服务")
    return fs
}

func main() {
    // 根命令只做分派，参数解析交给对应的子命令函数。
    if len(os.Args) 

关键点有两个：参数注册发生在对应的 FlagSet 上，而不是包级函数 flag.String；Usage 闭包引用当前的 fs，所以调用 PrintDefaults 时打印的是当前子命令的定义。

分别处理帮助请求和未知命令

使用 ContinueOnError 后，-h 会让当前 FlagSet 的解析返回帮助相关结果，错误参数也会返回错误。根命令要把这类结果留在当前分支处理，不要把 config 的解析错误误判成 serve 的业务错误。

func runServe(args []string, out io.Writer) error {
    fs := newServeCommand(out)
    // Parse 只接收 serve 后面的参数，根命令参数不会再次进入这里。
    if err := fs.Parse(args); err != nil {
        // ContinueOnError 让调用方保留恢复、测试或统一退出的选择。
        return err
    }
    return nil
}

func dispatch(args []string, out io.Writer) error {
    if len(args) == 0 {
        return fmt.Errorf("缺少子命令")
    }
    // 子命令名称只负责选择解析器，剩余切片交给该解析器。
    switch args[0] {
    case "serve":
        return runServe(args[1:], out)
    case "config":
        fs := newConfigCommand(out)
        return fs.Parse(args[1:])
    default:
        return fmt.Errorf("未知子命令：%s", args[0])
    }
}

如果希望把帮助请求当作正常流程，可以在调用处单独识别 flag.ErrHelp；如果只是把帮助文本写出后结束，也可以直接返回错误给统一的 CLI 入口。重要的是，处理决策发生在当前子命令上下文里。

让 Usage 同时承担参数边界说明

自定义 Usage 不只是换一行标题。它还可以解释位置参数、默认值和互斥关系，但建议把逻辑保持在当前子命令函数附近，避免 Usage 变成一段无法维护的长字符串。

func newConfigCommand(out io.Writer) *flag.FlagSet {
    fs := flag.NewFlagSet("config", flag.ContinueOnError)
    // 自定义输出能明确指出位置参数和配置检查的关系。
    fs.SetOutput(out)
    fs.Usage = func() {
        fmt.Fprintln(out, "用法：tool config [选项] ")
        fmt.Fprintln(out, "示例：tool config -file prod.yaml production")
        fs.PrintDefaults()
    }
    fs.String("file", "app.yaml", "配置文件路径")
    fs.Bool("check", false, "只检查配置，不写入文件")
    return fs
}

这里的 Usage 只描述 config，不应该顺手把 serve 的 -port 也列出来。若两个子命令需要相同的全局选项，可以在分派层显式处理，或者抽成创建函数后分别注册；不要因为复用方便而重新回到一个全局 FlagSet。

用三组命令确认输出范围

写完后重点观察帮助内容的边界，而不是只看程序能否启动。可以按下面三种情况检查：

如果两个帮助页面完全相同，优先检查是不是仍然调用了顶层 flag.PrintDefaults 或把参数注册到了 flag.CommandLine。如果帮助标题对了但参数列表为空，检查自定义 Usage 是否调用了当前 FlagSet 的 PrintDefaults。

小结：把解析器边界留在子命令内部

Go flag 为子命令分别生成帮助信息的核心只有三步：用 NewFlagSet 创建独立解析器，在每个解析器上注册参数，再通过 SetOutput 和 Usage 定义当前命令的说明。根命令只做名称分派，子命令负责参数解析和错误语义，帮助文本就不会互相污染。

相关问题：

• 为什么多子命令不建议共用包级 flag.String？
• ContinueOnError 和 ExitOnError 如何选择？
• 怎样把子命令的帮助输出写入测试缓冲区？
• 未知参数应由子命令返回还是由根命令统一处理？