Go flag.FlagSet 怎样让参数错误返回给调用方

我把一个命令行入口抽成可复用函数时，最先踩到的坑不是参数定义，而是错误处理：传入未知参数后，程序直接结束，调用方连包装错误、记录上下文的机会都没有。这个行为通常来自默认命令行 FlagSet 的退出策略，而不是业务函数主动调用了退出。

如果目标是“让参数错误返回给调用方”，关键写法是使用 flag.NewFlagSet(name, flag.ContinueOnError)，再检查 Parse 的返回值。ExitOnError 会调用 os.Exit，PanicOnError 会触发 panic，它们都不适合普通库函数把错误交给上层。

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

在可复用函数、子命令分发器和测试代码里，优先创建独立的 FlagSet 并选择 ContinueOnError；在最外层 CLI 入口再决定是否把最终错误转换成退出码。

三种 ErrorHandling 策略到底差在哪里

FlagSet.Parse 解析失败时，行为由 ErrorHandling 决定。Go 官方定义了三种策略：

这里还有一个容易忽略的区别：包级的默认命令行对象倾向于服务“一个程序一个入口”的场景；独立的 FlagSet 则允许每个子命令拥有自己的参数集合和错误策略。对我来说，是否能把策略作为构造参数看清楚，比记住某个全局默认值更重要。

用 ContinueOnError 让 Parse 返回错误

最小可用写法是把参数切片作为函数输入，不直接读取 os.Args。这样函数的输入边界清楚，调用方可以自行决定如何展示错误。

package main

import (
	"flag"
	"fmt"
)

func parseArgs(args []string) (string, error) {
	// 独立 FlagSet 把解析策略限定在当前函数，不影响进程里的其他参数。
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	name := fs.String("name", "guest", "任务名称")

	// Parse 失败时返回描述性 error，调用方仍然拥有控制权。
	if err := fs.Parse(args); err != nil {
		return "", err
	}
	return *name, nil
}

func main() {
	name, err := parseArgs([]string{"-unknown"})
	if err != nil {
		// 最外层可以决定记录日志、显示提示或转换为退出码。
		fmt.Printf("参数错误：%v\n", err)
		return
	}
	fmt.Println("任务名称：", name)
}

在这个边界上，未知参数不会让 parseArgs 直接结束进程。需要注意的是，ContinueOnError 解决的是“失败策略”，不是“忽略错误”：调用方仍然必须检查返回值，否则可能继续使用不完整的参数状态。

把诊断输出和返回错误分开

我第二次调整时发现，库函数即使不退出，也可能把用法和错误信息写到默认输出。对命令行主程序这很方便，对库和测试却可能造成重复输出。可以为当前 FlagSet 设置一个独立的 writer，让调用方决定是否展示这些诊断。

package main

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

func parseArgs(args []string) (string, string, error) {
	var diagnostics bytes.Buffer
	// 把 flag 的用法和错误诊断收集起来，避免库函数抢占进程标准错误输出。
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	fs.SetOutput(&diagnostics)
	name := fs.String("name", "guest", "任务名称")

	// 返回值负责表达失败，diagnostics 负责保留给用户看的辅助信息。
	if err := fs.Parse(args); err != nil {
		return "", diagnostics.String(), err
	}
	return *name, diagnostics.String(), nil
}

func main() {
	name, diagnostics, err := parseArgs([]string{"-name"})
	if err != nil {
		// 调用方可以把错误和诊断合并到自己的日志或响应模型。
		fmt.Printf("%s参数错误：%v\n", diagnostics, err)
		return
	}
	fmt.Println(name)
}

这个拆分让接口语义更稳定：error 用于程序判断，诊断文本用于人读。若产品不需要默认用法输出，也可以把输出设置为丢弃 writer；但这属于输出策略，不能替代对 Parse 返回值的检查。

什么时候才使用 ExitOnError 或 PanicOnError

我现在会把错误策略放在“谁拥有进程生命周期”这一层判断，而不是看代码长短：

• 最外层 CLI 入口：参数错误意味着程序无法继续时，可以选择 ExitOnError，或者使用 ContinueOnError 后在 main 里统一打印并返回退出码。
• 可复用包和子命令：优先 ContinueOnError，因为它不会替调用方做进程级决策。
• 内部不变量：只有当错误代表“按设计不应该发生”的状态，并且上层明确用 recover 处理时，才考虑 PanicOnError。

ExitOnError 的代价是测试隔离困难：一旦错误输入进入解析路径，当前进程就会退出。PanicOnError 的代价是调用方必须面对 panic，而不是常规的错误返回。两者都可以有明确场景，但不该因为写起来少一行就放进公共函数。

测试时重点覆盖哪些输入

围绕这个标题，测试不需要验证复杂的帮助排版，重点是确认错误边界没有被改回进程控制：

func TestParseArgs(t *testing.T) {
	tests := []struct {
		name string
		args []string
		wantErr bool
	}{
		{"正常参数", []string{"-name", "backup"}, false},
		{"未知参数", []string{"-unknown"}, true},
		{"缺少值", []string{"-name"}, true},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// 每个用例都创建独立解析器，避免已解析状态互相污染。
			_, err := parseArgs(tt.args)
			if (err != nil) != tt.wantErr {
				t.Fatalf("error = %v, wantErr = %v", err, tt.wantErr)
			}
		})
	}
}

如果需要专门测试帮助请求，还要区分 flag.ErrHelp 与普通参数错误；不要把所有非 nil 错误都当作同一种用户提示。测试的核心不是检查错误字符串的每个字符，而是确认错误能回到调用方，并且不存在意外退出或 panic。

最后的选择可以浓缩成一张表

我的经验是：只要函数被测试、复用或嵌入到别的程序里，就先用 ContinueOnError；把退出和 panic 留给真正拥有进程生命周期的上层。这样参数错误才会像普通业务错误一样回到调用方，而不是把调用方一起带走。

相关问题

• ContinueOnError 会不会完全关闭帮助输出？不会，它主要改变失败后的控制流；输出仍可通过 SetOutput 和 Usage 自行管理。
• 为什么不直接使用全局 flag.Parse？全局对象适合单一 CLI 入口，复用函数需要独立参数切片和独立错误边界。
• 多个子命令能共用一个 FlagSet 吗？通常不建议；每个子命令创建自己的 FlagSet，更容易隔离参数定义和解析状态。