Go flag 包如何组织子命令参数：FlagSet、错误输出与帮助信息边界

命令行工具从一个入口长成两个或三个子命令后，最容易失控的地方不是参数数量，而是参数到底由谁解释。把所有选项塞进同一个全局 flag.CommandLine，短期能跑，后面却会出现 serve 的端口选项影响 inspect、帮助信息混在一起、错误输出无法被脚本稳定判断等问题。Go 标准库的 flag.FlagSet 正好提供了一个清晰边界：每个子命令拥有自己的参数集合、输出目标和错误策略。

把子命令当成独立接口设计：参数只归属于自己的 FlagSet，解析失败统一返回错误，帮助信息走专门分支，主函数只负责选择命令和返回最终状态。

先确定调用方真正需要的接口

假设工具名是 bundlectl，它有两个任务：serve 启动本地预览服务，inspect 查看一个归档文件的基本信息。两个命令都可能需要“输入路径”，但这并不意味着它们应该共用一个全局 FlagSet。

serve 更关心监听地址和静态目录；inspect 更关心归档路径和是否打印校验摘要。把这些参数分开，调用方看到的帮助信息才是当前任务的最小契约。

让每个子命令拥有自己的参数预算

下面的构造函数只负责声明参数，不在声明阶段读取环境变量，也不把默认值偷偷写进另一个命令的配置。这样做的好处是：测试可以独立传入参数，帮助文本也不会出现无关选项。

type serveOptions struct {
	addr string
	root string
}

type inspectOptions struct {
	file    string
	摘要 bool
}

func newServeFlagSet(out, errOut io.Writer) (*flag.FlagSet, *serveOptions) {
	fs := flag.NewFlagSet("serve", flag.ContinueOnError)
	fs.SetOutput(errOut)
	opts := &serveOptions{}
	fs.StringVar(&opts.addr, "addr", ":8080", "监听地址")
	fs.StringVar(&opts.root, "root", ".", "静态目录")
	return fs, opts
}

func newInspectFlagSet(errOut io.Writer) (*flag.FlagSet, *inspectOptions) {
	fs := flag.NewFlagSet("inspect", flag.ContinueOnError)
	fs.SetOutput(errOut)
	opts := &inspectOptions{}
	fs.StringVar(&opts.file, "file", "", "归档文件路径")
	fs.BoolVar(&opts.摘要, "summary", false, "打印摘要")
	return fs, opts
}

这里有一个实际取舍：inspect 的字段名可以继续用中文，但 Go 团队代码通常更适合使用英文标识符。为避免示例把语言混用成新的问题，生产代码建议将字段命名为 summary；命令行用户看到的仍然是 --summary。

解析顺序决定错误归属

主函数只做三件事：判断第一个位置参数是哪一个子命令，把剩余参数交给对应 FlagSet，最后把业务错误转成统一的返回状态。不要先用全局解析器扫一遍，再把剩余参数交给子命令；那样未知选项很可能在错误的层级被拦截。

func run(args []string, out, errOut io.Writer) error {
	if len(args) == 0 {
		return errors.New("缺少子命令：serve 或 inspect")
	}

	switch args[0] {
	case "serve":
		fs, opts := newServeFlagSet(out, errOut)
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		return runServe(*opts)
	case "inspect":
		fs, opts := newInspectFlagSet(errOut)
		if err := fs.Parse(args[1:]); err != nil {
			return err
		}
		if opts.file == "" {
			return errors.New("inspect 必须提供 --file")
		}
		return runInspect(*opts)
	default:
		return fmt.Errorf("未知子命令 %q", args[0])
	}
}

关键点在于 ContinueOnError。它让解析器把错误交回 run，测试可以直接断言返回值，而不是启动一个新进程才能验证错误情况。

帮助、未知参数和业务错误要分开

用户请求 --help 时，看到帮助文本是成功的交互；用户传入未知选项时，应该得到参数错误；参数格式正确但文件不存在时，才是业务错误。这三种状态如果都只打印一句“失败”，脚本和人工排查都很困难。

func runInspectCommand(args []string, out, errOut io.Writer) error {
	fs, opts := newInspectFlagSet(errOut)
	fs.Usage = func() {
		fmt.Fprintln(out, "用法：bundlectl inspect --file archive.zip [--summary]")
		fs.PrintDefaults()
	}
	if err := fs.Parse(args); err != nil {
		if errors.Is(err, flag.ErrHelp) {
			return nil
		}
		return err
	}
	if opts.file == "" {
		return errors.New("--file 不能为空")
	}
	return runInspect(*opts)
}

这里不要依赖具体的英文错误文案做业务判断，调用方更应该判断返回错误类型或进程返回状态。帮助路径可以返回 nil，未知参数和缺少必要字段则返回错误，日志内容交给顶层统一写到标准错误输出。

新增参数时守住兼容策略

给已有子命令加参数时，优先选择有安全默认值的可选项，例如给 serve 增加 --read-timeout。不要突然把原本可省略的路径改成必填，也不要让新参数改变旧参数的含义。若确实需要不兼容变更，单独增加新子命令比悄悄改变旧命令更容易迁移。

参数名也是接口的一部分。已经发布的 --addr 不要仅因为内部字段改名就换成 --listen；可以保留旧名一段时间，帮助信息中说明推荐写法，再在明确的版本边界里移除。

用表格驱动测试核对调用方体验

接口设计最终要落到可重复的测试。至少覆盖空参数、合法参数、帮助、未知参数和业务失败五组输入，并分别核对返回错误、帮助输出和错误输出。测试不必真的启动网络服务，runServe 与 runInspect 可以使用替身依赖。

func TestRunInspectCommand(t *testing.T) {
	cases := []struct {
		name    string
		args    []string
		wantErr string
	}{
		{name: "missing file", args: nil, wantErr: "--file 不能为空"},
		{name: "unknown option", args: []string{"--no-such"}, wantErr: "flag provided but not defined"},
		{name: "help", args: []string{"--help"}, wantErr: ""},
	}

	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			var out, errOut bytes.Buffer
			err := runInspectCommand(tc.args, &out, &errOut)
			if tc.wantErr == "" {
				if err != nil {
					t.Fatalf("want nil error, got %v", err)
				}
				return
			}
			if err == nil || !strings.Contains(err.Error(), tc.wantErr) {
				t.Fatalf("want error containing %q, got %v", tc.wantErr, err)
			}
		})
	}
}

如果未来替换错误文案，最好同步更新一个稳定的错误类型，而不是让测试依赖完整句子。帮助文本则要把默认值、参数用途和示例写清楚；它是用户发现接口的第一入口。

常见问题与边界

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

全局解析器适合非常小的单命令程序。出现子命令后复用它会让参数集合、输出目标和测试状态相互污染，尤其是包级初始化和重复测试时更明显。

为什么不在 FlagSet 内部直接退出？

库函数直接结束进程会让调用方失去恢复和测试机会。使用 ContinueOnError，由顶层决定最终返回状态，命令行程序和嵌入式调用都更灵活。

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

不要把这种未定义行为当成兼容契约。推荐固定为 bundlectl inspect --file archive.zip，并在帮助信息和测试中保持同一顺序。

最后核对一遍接口边界

一个可维护的 Go 子命令入口，应该能明确回答四个问题：哪个 FlagSet 负责这个参数，解析失败写到哪里，帮助请求如何结束，新增参数会不会改变旧调用。把这四点写进测试，flag.FlagSet 就不只是“把参数解析出来”的工具，而是一个稳定的小型接口层。