Go flag.FlagSet 设置输出到缓冲区后如何捕获错误信息

如果命令行参数写错后，程序直接把 usage 和错误信息打到标准错误，调用方就很难把它变成 API 响应、测试断言或结构化日志。Go 的做法是创建独立的 flag.FlagSet，把错误策略设为 flag.ContinueOnError，再用 SetOutput 指向 bytes.Buffer。解析结束后读取 Parse 的返回值和缓冲区文本，就能同时得到“是否失败”和“用户应该看到什么”。官方文档入口：https://pkg.go.dev/flag。

关键顺序是：先创建 ContinueOnError 的 FlagSet，再 SetOutput(&buf)，定义参数，最后 Parse。不要只读错误返回值，因为 usage 和具体错误通常写在输出目标中；也不要只读缓冲区，因为 flag.ErrHelp 等语义需要通过返回值判断。

先把输出和错误策略分开设置

SetOutput 只负责改变 usage 与错误文字的去向，不会改变参数解析规则；真正决定解析失败后是否退出进程的是 NewFlagSet 的第二个参数。库代码、HTTP 服务里的子命令适配层以及单元测试，通常都应该选择 ContinueOnError，把决策交给调用方。

package main

import (
    "bytes"
    "flag"
)

func newParser() (*flag.FlagSet, *bytes.Buffer, *string) {
    // ContinueOnError 让 Parse 返回错误，调用方可以决定如何展示。
    fs := flag.NewFlagSet("sync", flag.ContinueOnError)
    var output bytes.Buffer
    // SetOutput 同时接收 usage 和解析错误；nil 才会回到 os.Stderr。
    fs.SetOutput(&output)
    file := fs.String("file", "", "要处理的文件")
    return fs, &output, file
}

Parse 返回错误，缓冲区保存可展示文本

定义完参数后调用 Parse。未知参数、缺少值或值类型不正确时，返回值用于判断失败，缓冲区则保存用户可读的错误和 usage。这个模式适合把命令行入口嵌进测试、任务调度器或上层服务中。

func parseArgs(args []string) (string, string, error) {
    fs, output, file := newParser()
    // Parse 的参数不包含程序名，只传入待解析的参数切片。
    err := fs.Parse(args)
    if err != nil {
        // String 取出 usage 和错误说明，调用方可以写日志或返回响应。
        return "", output.String(), err
    }
    if *file == "" {
        // 自定义业务校验也可以复用同一缓冲区，但要保留独立的返回错误。
        return "", "缺少 -file 参数\n", errors.New("缺少 -file 参数")
    }
    return *file, output.String(), nil
}

例如传入 []string{"-unknown"} 时，err 不为空，output.String() 里会出现未知参数和用法提示。不要把输出文本当作错误类型比较；文本是给人看的，稳定的控制分支应依赖 err。

ErrHelp 和普通解析失败要分开处理

当 FlagSet 没有自定义 help 参数时，用户传入 -h 或 -help 会返回 flag.ErrHelp。它可能代表“用户主动请求帮助”，不一定是程序故障。可以用 errors.Is 分类，再决定返回成功帮助、参数错误或统一的退出码。

package main

import (
    "errors"
    "flag"
    "fmt"
)

func classify(err error, message string) error {
    // ErrHelp 是标准库提供的哨兵错误，不能用字符串相等代替判断。
    if errors.Is(err, flag.ErrHelp) {
        fmt.Print(message)
        return nil
    }
    // 其他错误保留原始 error，外层可以映射为参数错误响应。
    return fmt.Errorf("参数解析失败: %w", err)
}

测试时每次创建独立 FlagSet

不要在测试中反复修改全局 flag.CommandLine 来捕获错误。全局 FlagSet 可能已经注册测试框架或其他包的参数，测试之间也容易残留输出。把解析逻辑封装成接收参数切片的函数，每次调用都创建新的 FlagSet，断言会更稳定。

func TestParseArgsRejectsUnknownFlag(t *testing.T) {
    // 每次测试都创建新的 FlagSet，避免定义和输出相互污染。
    _, message, err := parseArgs([]string{"-unknown"})
    if err == nil {
        t.Fatal("期望未知参数返回错误")
    }
    // 断言稳定的业务片段，不要把完整 usage 文本当成长期协议。
    if !strings.Contains(message, "flag provided but not defined") {
        t.Fatalf("错误文本不完整: %q", message)
    }
}

示例测试还需要导入 testing 和 strings。文章中的代码重点是捕获方式；项目里如果只需要判断错误类型，应优先断言 err，只有产品文案或日志格式确实重要时才断言缓冲区内容。

几个容易踩到的边界

• SetOutput(nil)：文档约定 nil 会使用 os.Stderr，所以不要把 nil 当成“静默模式”。
• ExitOnError：解析失败可能直接退出进程，不适合需要返回错误的库函数和测试。
• 重复 Parse：一个 FlagSet 应围绕一次明确的参数输入使用；多次解析会让状态和输出边界变得难以理解。
• 业务校验：flag 只负责语法和类型，文件是否存在、参数组合是否允许，仍应在 Parse 成功后单独判断。

速查起来可以记成一句话：返回值回答“发生了什么”，缓冲区回答“应该展示什么”。将两者分层后，命令行程序既能保留标准库的 usage，又能把错误交给调用方做测试、日志或接口转换。

常见问题解答

1. 为什么设置了 SetOutput 还是拿不到错误？

先确认使用的是同一个 FlagSet，并且 SetOutput 在 Parse 之前调用。还要检查是否误用了全局 flag.Parse，因为全局对象和自建 FlagSet 的输出目标不是同一份。

2. 只调用 SetOutput 能阻止程序退出吗？

不能。SetOutput 只改变写出位置；要让 Parse 返回错误，创建 FlagSet 时应使用 flag.ContinueOnError。

3. 帮助信息应该算错误吗？

不一定。没有自定义 help 参数时，flag.ErrHelp 表示用户请求帮助。上层可以把缓冲区内容作为正常帮助响应，同时把未知参数等其他错误映射为参数错误。