Go flag.FlagSet 怎么捕获参数错误并自定义命令行输出

如果直接使用默认的 flag.Parse，遇到未知参数或参数类型错误时，程序通常会把提示写到标准错误并结束进程。命令行子命令、测试用例或需要统一错误码的服务更适合使用 flag.FlagSet：创建时选择 flag.ContinueOnError，再配合 SetOutput 和 Usage，就能拿到 error、接管输出，并把最终决策交给上层。

核心组合是：NewFlagSet("serve", flag.ContinueOnError) 负责不退出，SetOutput 负责输出去向，Usage 负责格式。不要把解析错误和业务执行错误混在一个分支里。

先把参数输入变成可返回的错误

FlagSet 的输入是一个独立的字符串切片，适合子命令或单元测试。ContinueOnError 表示解析失败时返回描述性错误；如果仍使用默认的 ExitOnError，未知参数会让当前进程直接退出，上层就没有机会统一处理。

package main

import (
    "flag"
    "fmt"
)

func parseServe(args []string) (string, int, error) {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    host := fs.String("host", "127.0.0.1", "监听地址")
    port := fs.Int("port", 8080, "监听端口")

    // Parse 只负责把字符串转换成已声明的参数，不在这里启动服务。
    if err := fs.Parse(args); err != nil {
        return "", 0, err
    }
    if fs.NArg() != 0 {
        // 非 flag 参数属于调用约束，交给上层和解析错误区分处理。
        return "", 0, fmt.Errorf("多余参数: %q", fs.Args())
    }
    return *host, *port, nil
}

这里的关键是不要在 Parse 失败后继续读取指针值。未知 flag、缺少值或整数转换失败都应立即返回；否则默认值和半解析状态容易被误当成有效配置。

把错误和用法输出到指定位置

SetOutput 设置 usage 与错误消息的目标；传入 nil 时会回到 os.Stderr。在测试、库函数或需要拼装统一响应的 CLI 中，可以传入 bytes.Buffer，避免解析层直接污染终端。

package main

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

func parseWithOutput(args []string) (string, error) {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    var out bytes.Buffer
    fs.SetOutput(&out) // 将错误和用法暂存，调用方可以记录或返回它。
    fs.String("host", "127.0.0.1", "监听地址")
    fs.Int("port", 8080, "监听端口")

    if err := fs.Parse(args); err != nil {
        // 同时返回原始 error 和可读输出，便于区分日志与用户提示。
        return fmt.Sprintf("%s: %v", out.String(), err), err
    }
    return out.String(), nil
}

生产程序可以把这个 Writer 换成 os.Stderr、日志适配器或请求响应缓冲区。要注意：SetOutput 只改变输出去向，不会改变错误处理策略，也不会把解析错误变成业务成功。

用 Usage 统一帮助信息和参数错误

Usage 是 FlagSet 上的函数字段。解析发生错误时，flag 会调用它；自定义函数中可以打印命令说明，再调用 PrintDefaults 展示已经声明的参数。这样帮助内容和错误输出共用同一份参数定义，不必手写第二套列表。

package main

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

func parseCommand(args []string, output io.Writer) error {
    fs := flag.NewFlagSet("serve", flag.ContinueOnError)
    fs.SetOutput(output)
    fs.Usage = func() {
        // 自定义标题后复用 PrintDefaults，避免帮助和真实参数定义脱节。
        fmt.Fprintln(output, "用法: app serve [选项]")
        fs.PrintDefaults()
    }
    fs.String("host", "127.0.0.1", "监听地址")
    fs.Int("port", 8080, "监听端口")

    // 上层可据此决定退出码；本函数不调用 os.Exit。
    return fs.Parse(args)
}

如果调用者传入 -h 或 -help，未显式声明对应 flag 时，返回值通常可以与 flag.ErrHelp 比较。帮助请求不一定是故障，建议单独映射为成功退出或专用响应。

让上层决定退出码和业务动作

一个实用的分层方式是：解析函数只返回配置和错误，main 再区分帮助、参数错误和真正的启动失败。

if err := parseCommand(os.Args[2:], os.Stderr); err != nil {
    // ErrHelp 是用户主动请求帮助，参数错误才进入失败退出码。
    if err == flag.ErrHelp {
        return
    }
    fmt.Fprintln(os.Stderr, "参数错误:", err)
    os.Exit(2)
}

实际项目中可以不调用 os.Exit，而是由 main 返回状态，或把结果交给测试断言。重点是不要在库函数里使用全局 flag.CommandLine 修改输出；每个子命令创建自己的 FlagSet，边界会更清楚。

常见问题

ContinueOnError 会自动阻止所有退出吗？ 它只改变 Parse 的错误处理方式；调用方仍可能在收到 error 后主动退出。

SetOutput 后为什么仍然拿到 error？ 输出 Writer 与返回值是两条信息通道，前者是给用户看的文字，后者是给程序判断的结果，两者都应保留。

Usage 里要不要手写每个参数？ 通常不需要。先写简短用法说明，再调用 PrintDefaults，可以让帮助内容跟随参数定义变化。

总结一下：需要可测试、可组合的命令行解析时，先用 ContinueOnError 接住失败，再用 SetOutput 管住输出，最后用 Usage 统一帮助格式。解析层返回 error，退出码和业务动作留给更外层决定。