Go flag.FlagSet构建独立子命令解析器的组织方式

当一个 Go 命令同时提供 serve、export、check 等子命令时，继续把所有参数注册到全局 flag.CommandLine，很快就会遇到默认值串扰、帮助信息过长和错误输出难以归属的问题。更稳妥的组织方式是：根层只识别子命令名称，每个子命令各自创建一个 flag.FlagSet，再由子命令函数负责解析自己的参数。

用独立 FlagSet 把子命令参数隔离开

FlagSet 是一组独立的命令行参数定义，方法名与顶层 flag 函数基本对应。根命令可以先读取 os.Args[1]，然后把剩余参数交给对应的解析器。这样 serve 的 -port 不会出现在 export 的帮助信息里，新增子命令也不需要继续修改全局变量。

ContinueOnError 让解析错误回到调用方

子命令解析器适合使用 flag.ContinueOnError。未知选项或值转换失败时，Parse 返回错误，主流程可以决定返回退出码、记录日志，或者在测试中直接断言。若使用默认的 ExitOnError，解析失败会直接退出进程，不利于复用。

package main

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

// newFlagSet 为每个子命令创建独立的参数表和输出通道。
func newFlagSet(name string, out *bytes.Buffer) *flag.FlagSet {
	fs := flag.NewFlagSet(name, flag.ContinueOnError)
	fs.SetOutput(out)
	fs.Usage = func() {
		// 自定义 Usage，让帮助信息只描述当前子命令。
		fmt.Fprintf(out, "用法: tool %s [选项]\n", name)
		fs.PrintDefaults()
	}
	return fs
}

func run(args []string) error {
	if len(args) == 0 {
		return fmt.Errorf("缺少子命令，支持 serve 或 export")
	}

	switch args[0] {
	case "serve":
		var output bytes.Buffer
		fs := newFlagSet("serve", &output)
		port := fs.Int("port", 8080, "监听端口")
		if err := fs.Parse(args[1:]); err != nil {
			// 保留 FlagSet 的帮助和错误文本，交给统一出口处理。
			return fmt.Errorf("serve 参数错误: %s%w", output.String(), err)
		}
		if fs.NArg() != 0 {
			return fmt.Errorf("serve 不接受位置参数: %v", fs.Args())
		}
		fmt.Printf("serve port=%d\n", *port)
	case "export":
		var output bytes.Buffer
		fs := newFlagSet("export", &output)
		format := fs.String("format", "json", "导出格式")
		if err := fs.Parse(args[1:]); err != nil {
			return fmt.Errorf("export 参数错误: %s%w", output.String(), err)
		}
		fmt.Printf("export format=%s files=%v\n", *format, fs.Args())
	default:
		return fmt.Errorf("未知子命令 %q", args[0])
	}
	return nil
}

func main() {
	if err := run(os.Args[1:]); err != nil {
		// main 统一决定错误输出与退出码，子命令函数不直接 os.Exit。
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}
}

这里的关键不是把代码拆成更多函数，而是让 FlagSet 成为子命令的边界。serve 和 export 可以拥有同名参数，也可以使用不同的默认值；它们的解析状态不会共享。

把错误输出、帮助信息和位置参数分开处理

SetOutput 可以把当前解析器写入的帮助与错误文本导向缓冲区、日志或测试用的 bytes.Buffer。配合自定义 Usage，调用方可以保留“哪个子命令出错”的上下文，而不必让底层函数直接打印或退出。

位置参数则通过 fs.Args() 读取，fs.NArg() 判断数量。需要特别注意：Go 的 flag 解析遇到第一个非 flag 参数就会停止继续解析。因此 tool export input.csv -format csv 不应被当成“先读文件、再设置格式”；如果格式是选项，应写成 tool export -format csv input.csv。

把解析边界固定成可测试的执行入口

建议把“参数解析”和“真正执行”保持在同一个子命令函数内，但让函数返回 error。这样可以分别测试空参数、未知 flag、错误类型和多余位置参数，而 main 只负责接收错误、输出信息并选择退出码。

如果子命令数量继续增加，可以把每个解析函数改成 runServe、runExport，再由根分派器维护名称到函数的映射。只要每个函数继续拥有自己的 FlagSet，帮助、默认值、错误输出和测试边界就不会重新耦合。

相关问题

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

全局集合适合只有一层参数的简单程序；子命令共享它会让不同命令的选项、默认值和帮助文本互相暴露。

ContinueOnError 会不会自动打印错误？

解析器会按自己的输出设置写入诊断信息，同时把错误返回给调用方；调用方仍应统一决定日志格式和退出码。

位置参数和 flag 可以混写吗？

应把选项放在位置参数前。解析在第一个非 flag 参数处停止，后面的内容通常会留在 Args() 中。

官方参考：https://pkg.go.dev/flag