Go FlagSet 怎样让子命令独立解析

Go 标准库的 flag.FlagSet 可以让每个子命令拥有独立的参数集合：先从 os.Args 找到子命令名称，再把后面的切片交给对应的 FlagSet.Parse。这样 serve 只认识服务参数，export 只认识导出参数，两个命令不会因为共享全局 flag 而互相污染。

官方文档：https://pkg.go.dev/flag

下面用一个只依赖标准库的 CLI 场景说明组织方式。示例把“选择哪个命令”和“解析这个命令的选项”拆成两层，便于继续添加第三个子命令，也方便在测试时直接传入参数切片。

先把命令行拆成三块

一个简单的子命令 CLI 可以把参数理解为三块：程序名、子命令名称、子命令自己的参数。例如 tool serve -addr :9000 中，tool 是程序名，serve 是路由键，-addr :9000 才是 serve 的输入。

关键点是不要把整个 os.Args 再交给子命令的解析器。官方文档说明，FlagSet.Parse 接收的参数列表不应包含命令名；在子命令分发完成后，传入 args[2:] 才能保持边界清楚。

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

flag.NewFlagSet 返回一个空的参数集合。创建时使用 flag.ContinueOnError，可以让解析错误作为返回值交给上层，而不是由库直接结束进程。每个函数只在自己的集合上注册参数，解析结果也只写入自己的局部变量。

package main

import (
	"flag"
	"fmt"
)

// parseServe 只处理 serve 子命令的参数，不读取 export 的选项。
func parseServe(args []string) error {
	fs := flag.NewFlagSet("serve", flag.ContinueOnError)
	addr := fs.String("addr", ":8080", "监听地址")
	verbose := fs.Bool("verbose", false, "输出详细日志")
	if err := fs.Parse(args); err != nil {
		return err
	}
	if fs.NArg() != 0 {
		return fmt.Errorf("serve 不接受位置参数: %v", fs.Args())
	}
	fmt.Printf("serve addr=%s verbose=%t\\n", *addr, *verbose)
	return nil
}

// parseExport 重新创建 FlagSet，因此 -format 不会进入 serve 的解析空间。
func parseExport(args []string) error {
	fs := flag.NewFlagSet("export", flag.ContinueOnError)
	format := fs.String("format", "json", "导出格式")
	out := fs.String("out", "-", "输出目标")
	if err := fs.Parse(args); err != nil {
		return err
	}
	if fs.NArg() != 1 {
		return fmt.Errorf("export 需要一个输入文件，当前参数: %v", fs.Args())
	}
	fmt.Printf("export input=%s format=%s out=%s\\n", fs.Arg(0), *format, *out)
	return nil
}

这里没有使用包级别的 flag.String，因为包级 API 默认绑定到全局 CommandLine。子命令各自创建 FlagSet 后，addr、verbose、format 和 out 的生命周期都被限制在对应函数里，参数命名也可以按命令语义独立演进。

在入口处分发，再交给对应解析器

分发函数只负责确认子命令是否存在和切出参数，不把具体业务选项塞到一个巨大的 switch 里。切片表达式 args[2:] 只是去掉程序名与命令名，不会复制底层元素；对这种短命令行参数足够直接。

package main

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

// dispatch 负责路由；子命令函数负责注册和解析自己的参数。
func dispatch(args []string) error {
	if len(args)  [选项]", args[0])
	}

	command := args[1]
	subArgs := args[2:] // 子命令解析器不应再次看到程序名和命令名。
	switch command {
	case "serve":
		return parseServe(subArgs)
	case "export":
		return parseExport(subArgs)
	default:
		return fmt.Errorf("未知子命令 %q", command)
	}
}

func main() {
	// 入口只把错误转成退出码，避免解析函数自行 os.Exit 而难以测试。
	if err := dispatch(os.Args); err != nil {
		fmt.Fprintln(os.Stderr, err)
		flag.PrintDefaults()
		os.Exit(2)
	}
}

真实项目里可以把 flag.PrintDefaults 换成根命令自己的帮助函数；这里重点是错误沿调用链返回。若希望每个子命令显示自己的帮助信息，可以在对应的 FlagSet 上调用 SetOutput 和自定义 Usage，不必把所有帮助文本集中到全局集合。

完整入口为什么要保留 ContinueOnError

ContinueOnError 的价值不只是“不退出”。它让 Parse 返回未知选项、非法值或帮助请求产生的结果，上层可以决定打印到哪里、是否记录上下文、最后使用什么退出码。对于库函数或测试调用，这比在深层解析函数里直接结束进程更容易复用。

子命令的解析边界还受到 flag 语法影响：标准库支持一个或两个短横线；解析会在第一个非 flag 参数或终止符 -- 前停止。若 export 需要接收以短横线开头的文件名，应先理解这一规则，再明确约定 -- 后的内容作为位置参数，而不是把它当成另一个选项。

公共参数应该放在哪里

如果多个子命令确实共享 --config 或 --profile，可以在分发前用一个根级 FlagSet 解析公共前缀，再把剩余切片交给子命令；也可以在每个子命令重复注册同名参数。选择哪种方式取决于命令行契约，不要为了少写几行就让子命令偷偷读取全局变量。

无论选择哪种方案，解析结果都应通过结构体或函数参数传递给后续业务。不要让 parseServe 修改一个供 parseExport 复用的包级变量，否则“独立解析”只停留在 FlagSet 名称上，测试之间也容易互相留下状态。

几个容易混淆的边界

• FlagSet 不是自动的子命令路由器：它只负责一组 flag 的定义和解析，命令名称仍需要你自己从参数中选择。
• Parse 不应该重复吃命令名：先切出 subArgs，否则命令名会成为第一个位置参数或干扰错误提示。
• Args 与 NArg 是解析后的剩余参数：如果命令允许输入文件、资源名或目标环境，应在业务规则中检查数量。
• 不要共享可变解析器：同一个 FlagSet 不适合在多个独立调用中不断追加同名 flag；每次构造或明确复用生命周期。
• 帮助和错误要有出口：设置 ContinueOnError 后，调用方仍要处理 Parse 返回的错误和帮助结果。

常见问题

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

全局集合适合一个简单命令只有一组参数的场景。多个子命令共用它时，所有选项处在同一命名空间，子命令之间容易出现同名冲突，也难以限制某个选项只属于某一个命令。

子命令参数可以放在命令名前面吗？

可以设计成根级参数，但那就属于根命令的语法。本文的约定是先出现子命令，再由对应的 FlagSet 解析后续参数；不要让文档写一种顺序、代码却按另一种顺序切片。

什么时候应该换用 Cobra 等库？

如果只需要少量子命令、短帮助文本和明确的错误返回，标准库足够。需要嵌套命令、自动补全、复杂参数继承或统一文档生成时，再根据项目依赖策略评估专用库，不必为了“子命令”三个字立即引入依赖。

用 FlagSet 实现子命令的核心只有一句话：路由层决定把哪一段参数交给谁，子命令层只解析自己的那一段。保留这个边界后，新增命令、检查位置参数和编写测试都会更简单。