Go flag.FlagSet 怎么把参数解析错误改写到指定 Writer

在 Go 命令行程序里，参数写错后经常会同时看到一行错误和一段 usage。默认情况下，这些文字会走标准错误输出；如果代码需要测试、嵌入服务，或者有多个子命令，就应该把输出目标和错误控制权交给调用方。

解决办法是把两个职责拆开：用 FlagSet.SetOutput(w) 指定 usage 与错误消息写到哪里，用 flag.ContinueOnError 让 Parse 返回错误，而不是直接退出进程。这样，bytes.Buffer、日志适配器或测试自己的 Writer 都能接住这条链路。

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

如果目标是“捕获错误并继续由上层处理”，先创建带 ContinueOnError 的 FlagSet，再调用 SetOutput。SetOutput 只负责输出去向，不负责改变 Parse 出错后的控制流。

先把默认行为看清楚

flag.NewFlagSet(name, errorHandling) 同时接收命令名称和错误处理模式。普通的解析失败可能来自未知参数、缺少值或值格式不正确。默认的 usage 函数会把帮助文本写入 FlagSet 的输出目标；当输出目标没有被改写时，标准库使用 os.Stderr。

因此，下面三个问题其实属于两条不同的链路：

• 文字写到哪里：由 SetOutput 决定，传入 nil 会回到 os.Stderr。
• 错误之后谁做决定：由 ErrorHandling 决定，ContinueOnError 返回错误，另外两种模式会退出或 panic。
• usage 长什么样：由 Usage 函数决定；没有自定义函数时使用默认 usage。

这个拆分很重要：只调用 SetOutput，并不会让 Parse 自动变成可恢复模式；只选择 ContinueOnError，也不会把文字从标准错误输出转到测试缓冲区。

用 ContinueOnError 捕获参数解析错误

命令行程序通常需要让 main 决定退出码，而单元测试更需要拿到错误对象和输出文字。下面的最小例子把两者都交给调用方：

package main

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

func parseArgs(args []string) (string, string, string, error) {
	var out bytes.Buffer
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	// 把错误行和 usage 都收进同一个 Writer，便于测试或上层记录。
	fs.SetOutput(&out)

	input := fs.String("input", "", "输入文件")
	format := fs.String("format", "text", "输出格式")
	if err := fs.Parse(args); err != nil {
		// 错误对象负责控制流，out.String() 负责给调用方展示上下文。
		return "", out.String(), err.Error(), err
	}
	return *input, *format, out.String(), nil
}

func main() {
	input, format, output, err := parseArgs([]string{"-input"})
	if err != nil {
		// main 可以在这里统一决定退出码、日志级别或帮助文案。
		fmt.Printf("parse failed: %v\\n%s", err, output)
		return
	}
	fmt.Printf("input=%s format=%s\\n", input, format)
}

调用 -input 而不提供值时，Parse 返回错误，错误文字和 usage 都进入 out。这里没有调用 os.Exit，所以测试可以继续执行，也可以把错误转换成自己的业务错误。

对于未知参数也一样：

func captureUnknownFlag() (string, error) {
	var out bytes.Buffer
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	// 测试只关心这次解析产生的文字，不能让它污染进程级 stderr。
	fs.SetOutput(&out)
	fs.String("input", "", "输入文件")

	err := fs.Parse([]string{"-verbose"})
	// 先返回原始 error，再由断言检查输出中是否包含参数名。
	return out.String(), err
}

不要只断言输出文本就结束。输出适合给人看，error 适合控制分支；两者应该分别承担职责。尤其是未来调整 usage 排版时，基于完整字符串的测试更容易变得脆弱。

SetOutput 只改目的地，不改 usage 规则

如果产品希望错误信息统一成“参数错误，请使用 --help”，可以自定义 Usage，但仍然建议让自定义函数通过 fs.Output() 写出。这样，调用方替换 Writer 后，usage 不会偷偷绕回标准错误输出。

func newWorkerFlags(w io.Writer) *flag.FlagSet {
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	// 所有标准库生成的错误和自定义 usage 共享同一输出目标。
	fs.SetOutput(w)
	fs.String("input", "", "输入文件")
	fs.String("format", "text", "输出格式")
	fs.Usage = func() {
		// Output() 会返回当前 Writer；不要在这里硬编码 os.Stderr。
		fmt.Fprintln(fs.Output(), "用法：worker -input 文件 [-format text|json]")
		fs.PrintDefaults()
	}
	return fs
}

上面代码需要补充 io 和 fmt 导入。关键点不是把 usage 改成哪一句，而是让它继续使用 FlagSet 自己的输出目标。如果把 fmt.Fprintln(os.Stderr, ...) 写死，SetOutput 只对标准库内部消息生效，自定义 usage 仍会从另一条通道漏出去。

还有一个常见误区：SetOutput(nil) 不是“关闭输出”，而是恢复使用标准错误输出。若确实不想看到文字，应显式传入一个会丢弃数据的 Writer，例如 io.Discard，但命令行工具要谨慎使用，否则用户失去定位参数错误的线索。

三种错误处理模式该怎么选

FlagSet 的错误处理模式决定 Parse 返回错误后程序如何继续：

三种模式都可以配合 SetOutput，但只有第一种适合把解析逻辑封装成普通函数。若库代码内部使用 ExitOnError，调用方即使设置了自己的 Writer，也无法在错误后恢复业务流程。

按使用场景落地

单元测试：每次创建独立 FlagSet

测试中不要反复修改全局 flag.CommandLine，因为它会让测试之间共享参数定义、输出目标和解析状态。每个用例创建自己的 FlagSet，把 Writer 设成 buffer，再断言错误类型或关键片段。

func TestParseArgsRejectsUnknownFlag(t *testing.T) {
	var out bytes.Buffer
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	// 独立 FlagSet 避免测试之间共享全局参数和输出状态。
	fs.SetOutput(&out)
	fs.String("input", "", "输入文件")

	err := fs.Parse([]string{"-unknown"})
	if err == nil {
		t.Fatal("期望未知参数返回错误")
	}
	if !strings.Contains(out.String(), "unknown") {
		// 只检查关键事实，避免把 usage 排版绑定进测试契约。
		t.Fatalf("输出未包含参数名：%q", out.String())
	}
}

这个测试片段需要引入 strings 和 testing。如果测试的是帮助行为，应单独传入 -h，并明确处理 flag.ErrHelp；不要把帮助请求和普通参数错误混为一类。

生产命令：让 main 决定用户体验

在真正的命令入口，解析函数可以返回结构化结果和错误，main 再决定是否打印简短提示、完整 usage 或设置退出码。这样可以让同一套解析逻辑被服务启动器、批处理任务和测试复用。

如果项目有多个子命令，每个子命令应拥有自己的 FlagSet 和 Writer。共享一个全局 FlagSet 会让不同子命令的参数定义互相影响，也会让错误消息难以判断来源。

一张清单记住边界

1. 要改变文字去向：调用 SetOutput(w)。
2. 要让调用方拿到错误：选择 ContinueOnError。
3. 要改变帮助格式：覆盖 Usage，并用 fs.Output() 输出。
4. 要恢复默认目标：传入 nil；要静默处理：显式传入 io.Discard。
5. 要写稳定测试：使用独立 FlagSet，分别断言 error 和输出中的关键片段。

把“输出写到哪里”和“错误之后怎么走”分开以后，flag.FlagSet 就不再是只能直接退出的黑盒。命令行入口可以保留清晰的 usage，测试可以捕获完整上下文，库函数也能把最终决策留给调用者。

相关问题

SetOutput 能不能只拦截错误、不拦截 usage？

标准库的默认错误处理会把错误文字和 usage 都写入 FlagSet 的输出目标。如果需要拆成两路，应自定义 Usage 或在调用层重新组织展示，但不要假设 SetOutput 只影响错误行。

为什么传入 nil 后又看到了 stderr 输出？

这是文档定义的行为：输出目标为 nil 时使用 os.Stderr。nil 表示恢复默认，而不是禁用输出。

库函数应该直接使用 ExitOnError 吗？

通常不应该。库函数结束宿主进程会削弱复用性；更稳妥的做法是使用 ContinueOnError，把错误交还给上层。