Go flag.FlagSet ContinueOnError 怎么捕获帮助输出和解析错误

我在给 Go 子命令补参数校验时，最容易踩的坑是：默认的 flag.CommandLine 会把错误和帮助直接写到标准错误，某些错误处理策略还会结束进程。这样一来，调用方既不好测试，也很难把“用户主动看帮助”和“参数真的写错”分开。

更适合库函数、子命令和测试的写法，是创建独立的 flag.FlagSet，选择 flag.ContinueOnError，再用 SetOutput 把提示文本交给自己的缓冲区。解析后检查返回值：errors.Is(err, flag.ErrHelp) 表示用户请求帮助，其他非空错误才是未知参数、缺少值或值格式不对。

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

捕获 Go flag 输出的关键不是拦截标准错误，而是让每个子命令拥有自己的 FlagSet、输出目标和错误分支。

先把退出行为改成可返回错误

flag.NewFlagSet 的第二个参数决定 Parse 失败后的行为。ContinueOnError 会返回描述性错误；ExitOnError 会退出进程；PanicOnError 会触发 panic。要在上层决定如何显示消息或设置退出码，应该选第一种。

下面的解析函数不读取 os.Args，而是接收参数切片。这样同一套代码可以被主程序调用，也可以在测试里传入不同的参数组合。

package main

import (
    "flag"
    "fmt"
)

func parseStart(args []string) error {
    // ContinueOnError 让调用方拿到错误，而不是让解析器直接结束进程。
    fs := flag.NewFlagSet("start", flag.ContinueOnError)
    addr := fs.String("addr", ":8080", "监听地址")

    // Parse 的参数不包含程序名；错误会由当前函数继续向上返回。
    if err := fs.Parse(args); err != nil {
        return fmt.Errorf("解析 start 参数失败: %w", err)
    }
    fmt.Println("准备监听", *addr)
    return nil
}

这里的 fmt.Errorf 使用了 %w，因此上层仍可以通过 errors.Is 检查被包装的错误类型。不要在这个函数里把所有错误都改成普通字符串，否则帮助请求的身份会丢失。

把帮助和错误输出接到缓冲区

SetOutput 设置的是 FlagSet 的帮助与错误消息输出目标；传入 nil 时会回到 os.Stderr。配合 bytes.Buffer，调用方就能在需要时把提示交给日志、HTTP 响应或测试断言。

package main

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

func parseWithOutput(args []string) (string, string, error) {
    var output bytes.Buffer
    fs := flag.NewFlagSet("convert", flag.ContinueOnError)

    // 默认 Usage 和解析错误都写入这个缓冲区，而不是直接写终端。
    fs.SetOutput(&output)
    input := fs.String("input", "", "输入文件")
    if err := fs.Parse(args); err != nil {
        // 同时保留原始 error 与已经生成的提示文本。
        return output.String(), "", err
    }
    return output.String(), *input, nil
}

func showResult(args []string) {
    // 传入未知参数时，调用方可以分别处理文本和错误。
    message, input, err := parseWithOutput(args)
    fmt.Printf("提示=%q 输入=%q 错误=%v\n", message, input, err)
}

未知参数、缺少参数值、值无法转换时，标准库会先把诊断和 Usage 写到 FlagSet 的输出，再返回错误。输出和错误是两条信息：前者给人看，后者给程序分支判断，不要只保存其中一个。

分别识别帮助请求与解析失败

当没有定义名为 help 或 h 的 flag 时，输入 -h 或 -help 会触发默认 Usage，并让 Parse 返回 flag.ErrHelp。未知 flag 则返回普通错误，例如 flag provided but not defined。这两个分支的用户意图不同：帮助通常不是失败，错误参数才需要提示修正。

package main

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

func parseCommand(args []string) (string, error) {
    var output bytes.Buffer
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    fs.SetOutput(&output)
    port := fs.Int("port", 8080, "服务端口")

    // 先解析，再用 errors.Is 保留对 ErrHelp 的识别能力。
    err := fs.Parse(args)
    switch {
    case err == nil:
        return fmt.Sprintf("启动端口=%d", *port), nil
    case errors.Is(err, flag.ErrHelp):
        // 用户主动请求帮助，不把它当成参数错误上报。
        return output.String(), nil
    default:
        // 解析错误保留原文，调用方可决定退出码或返回接口错误。
        return output.String(), fmt.Errorf("serve 参数无效: %w", err)
    }
}

如果项目自己定义了 -help 字段，它就不再走标准库的特殊 ErrHelp 分支，而是按普通 flag 解析。要统一行为，通常不要重复定义这个名字，直接消费 ErrHelp 和缓冲区里的 Usage 即可。

还有一个容易忽略的点：Parse 可能已经把前面的 flag 写入变量，然后在后面的参数处失败。返回非空错误时不要继续把部分变量当成完整配置使用；是否允许“部分解析”应由调用方明确决定。

覆盖自定义 Usage，避免重复打印

默认 Usage 适合标准 flag 列表，但子命令一般还需要一行用途说明、示例或参数分组。可以替换 fs.Usage，并让自定义函数继续使用 fs.Output()，这样 SetOutput 仍然有效。

package main

import (
    "flag"
    "fmt"
    "io"
)

func newServeFlags(out io.Writer) *flag.FlagSet {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    fs.SetOutput(out)
    fs.String("addr", ":8080", "监听地址")

    // 自定义 Usage 只负责说明格式，仍把内容写到 FlagSet 的输出目标。
    fs.Usage = func() {
        fmt.Fprintf(fs.Output(), "用法: serve [选项]\n\n选项:\n")
        fs.PrintDefaults()
    }
    return fs
}

不要同时在自定义 Usage 里打印一遍、在上层捕获错误后再打印一遍，否则一次错误会出现两份帮助。推荐约定为：解析器只产生一次标准文本，上层根据 ErrHelp 或普通错误选择是否展示缓冲区。

收束到测试和子命令工作流

我的实际工作流是把“构造 FlagSet、注入输出、解析参数、判断错误”放在一个小函数里。每次调用都创建新的 FlagSet，不复用已经 Parse 过的实例，也不让测试依赖全局标准错误。

package main

import (
    "bytes"
    "errors"
    "flag"
)

func parse(args []string) (string, error) {
    var buf bytes.Buffer
    fs := flag.NewFlagSet("tool", flag.ContinueOnError)
    fs.SetOutput(&buf)
    fs.Bool("verbose", false, "输出详细信息")

    // 每次调用都使用新的 FlagSet，避免上一次 Parse 的状态影响当前请求。
    err := fs.Parse(args)
    if errors.Is(err, flag.ErrHelp) {
        return buf.String(), nil
    }
    if err != nil {
        return buf.String(), err
    }
    return "", nil
}

测试时可以传入 []string{"-h"}、[]string{"-unknown"} 和合法参数，分别断言帮助文本、错误文本和 nil 错误。正式程序则可以把普通错误映射成退出码 2，把帮助映射成退出码 0；这一步属于应用层决策，ContinueOnError 本身不会替你退出。

最后记住三件事：ContinueOnError 负责把控制权交回调用方，SetOutput 负责把人类可读文本导向指定 Writer，flag.ErrHelp 负责标记未定义帮助 flag 的请求。把三者放进同一个解析边界，Go 标准库的命令行错误就能被可靠地捕获和测试。

相关问题

ContinueOnError 会自动阻止业务代码继续执行吗？

不会。它只让 Parse 返回错误；调用方必须检查返回值，并在错误分支中主动 return。

SetOutput 只会捕获错误，不会捕获帮助吗？

它同时控制 FlagSet 的 Usage 与错误消息输出。自定义 Usage 时也应使用 fs.Output()，不要写死到 os.Stderr。

为什么拿到 ErrHelp 还会有一段 Usage 文本？

标准库在识别未定义的 -h/-help 时会先调用 Usage，再返回 flag.ErrHelp；这是帮助请求的正常表现。