Go flag.FlagSet.Parse 如何区分未知参数与参数值：ContinueOnError、Usage 输出与退出控制

给 Go 命令增加子命令后，最容易混淆的是“参数名不存在”和“参数名存在但值不合法”。把 flag.FlagSet.Parse 放进 ContinueOnError 模式，再根据返回的错误和 Args 分流，既能保留调用方控制权，也能避免测试时被 os.Exit 打断。

实用判断是：未知参数、缺少参数值、-h 都先交给 Parse 和 Usage，业务代码只处理成功解析后的字段与剩余参数。

先把三类输入放到同一个 FlagSet

假设命令只接受 -format 和 -verbose 两个选项，其他内容作为要处理的文件名。不要直接使用包级 flag.Parse，因为它默认绑定全局命令行；子命令或单元测试更适合独立的 FlagSet。

package main

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

func parseArgs(args []string, out io.Writer) error {
    fs := flag.NewFlagSet("convert", flag.ContinueOnError)
    fs.SetOutput(out)
    format := fs.String("format", "json", "output format")
    verbose := fs.Bool("verbose", false, "print details")

    if err := fs.Parse(args); err != nil {
        return err
    }
    fmt.Fprintf(out, "format=%s verbose=%t files=%v\n", *format, *verbose, fs.Args())
    return nil
}

func main() {
    if err := parseArgs(os.Args[1:], os.Stderr); err != nil {
        os.Exit(2)
    }
}

这里的关键不是把错误吞掉，而是让 FlagSet 完成输入校验后，把决定权交回调用方。SetOutput 还能把用法和错误写进测试缓冲区，不必污染标准错误。

Parse 返回错误时，先区分未知参数和缺少值

ContinueOnError 的价值在于 Parse 返回错误，进程仍然留在当前函数里。比如 -unknown 会得到“flag provided but not defined”一类错误；-format 后没有值时，则是缺少参数值。两者都不应继续进入文件处理逻辑。

图片中的 FlagSet、Parse、ContinueOnError 与 Usage 对应上面的代码和标准库行为：先由 Parse 读取参数，错误时调用 Usage，再将错误返回给调用方；成功时才会继续读取指针字段。

func parse(args []string) (string, error) {
    var output bytes.Buffer
    fs := flag.NewFlagSet("convert", flag.ContinueOnError)
    fs.SetOutput(&output)
    fs.String("format", "json", "output format")
    fs.Usage = func() {
        fmt.Fprintln(&output, "usage: convert [options] file...")
    }
    if err := fs.Parse(args); err != nil {
        return output.String(), err
    }
    return output.String(), nil
}

需要自定义提示时改写 Usage 即可，不要在 Usage 里再次调用 Parse。解析失败后直接返回，调用方可以把错误映射成测试断言、CLI 返回码或上层提示。

-h 为什么不是普通的未知参数错误

当用户传入 -h 或 -help 时，标准 FlagSet 会展示用法并返回 flag.ErrHelp。这条分支通常表示用户主动请求帮助，不宜和配置错误显示同样的“失败”提示。

err := fs.Parse(args)
switch {
case err == nil:
    // 使用已经解析的字段。
case errors.Is(err, flag.ErrHelp):
    // Usage 已经输出，调用方按帮助路径结束。
default:
    // 未知参数、缺少值或值解析失败。
}

如果采用 ExitOnError，普通解析错误会直接结束进程；库代码和测试代码一般不应把这种退出策略硬编码进去。让外层程序决定退出码，复用性更好。

Args 如何承接文件名和子命令参数

Parse 遇到第一个非 flag 参数后，会把它以及后面的参数放入 fs.Args()。因此下面的输入中，report.csv 不会被当成未知选项，而是作为业务参数保留下来。

args := []string{"-format", "csv", "report.csv", "backup.csv"}
if err := fs.Parse(args); err != nil {
    return err
}
files := fs.Args()
// files: [report.csv backup.csv]

第二张图只表达一个数据路径：输入参数进入 Parse 后，format 进入已定义 flag，report.csv 和 backup.csv 进入 Args。这样图片解释的是正文中的真实数据流，不是泛化的命令行海报。

如果命令必须至少接收一个文件，校验应放在解析成功之后：

if len(fs.Args()) == 0 {
    return errors.New("missing input file")
}

不要把“没有文件”误判成 Parse 错误。flag 语法正确但业务参数不完整，是另一层校验。

测试时把输出和错误一起验收

测试可以传入一组固定参数，观察返回错误、用法输出和字段结果。最少覆盖三条路径：未知参数返回错误、-h 返回 flag.ErrHelp、合法参数留下预期的 Args。

func TestParseArgs(t *testing.T) {
    var out bytes.Buffer
    err := parseArgs([]string{"-unknown"}, &out)
    if err == nil || !strings.Contains(err.Error(), "not defined") {
        t.Fatalf("unexpected error: %v", err)
    }
    if !strings.Contains(out.String(), "usage") {
        t.Fatalf("usage not written: %q", out.String())
    }
}

常见问题：FlagSet.Parse 的边界怎么记

为什么不直接用 ExitOnError？

命令行最外层可以使用它，但可复用函数、子命令分发器和测试更需要拿到错误后自行决定下一步，通常选择 ContinueOnError。

Usage 输出后还要自己再打印一次吗？

一般不需要。解析失败时 Usage 会参与输出；调用方只需根据返回错误选择返回码或提示，避免同一段用法重复出现。

如何判断文件名是否缺失？

先确认 Parse 返回 nil，再检查 len(fs.Args())。flag 语法错误和业务参数不足是两个独立状态。

收尾检查

独立的 FlagSet 让参数边界变得可测试：ContinueOnError 保留控制权，Usage 统一提示，Args 接住剩余参数。把这三处职责分开，未知参数和业务校验就不会互相遮掩。