Go flag.Func 怎么校验自定义参数

flag.Func 适合校验标准库内置参数类型之外的规则。它接收原始字符串和一个 func(string) error 回调：参数每出现一次，回调就执行一次；返回非 nil 错误时，flag 会把它当作参数值解析失败。实用写法是“先解析到临时值，校验通过后再写入配置”，这样失败时不会留下半成品状态。

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

什么时候用 flag.Func

我最初会先用 flag.String 接收所有值，再在 Parse 后写一大段校验。参数一多，错误提示离参数定义越来越远，也很容易忘记阻止后续逻辑。flag.Func 的价值不是替代所有内置参数，而是让“这个参数怎样从字符串变成可信值”靠近定义位置。

典型场景包括限定环境只能是 dev、staging、prod，校验 host:port，拆分逗号列表，或者把字符串转换成领域对象。官方文档还明确指出，同一参数每出现一次都会调用回调，因此它也能实现累积列表，但是否允许重复必须由程序自己决定。

先校验再写入配置

下面示例把环境参数限制在三个值内。关键不是 switch 本身，而是先得到局部变量 env，确认合法后才赋给 cfg.Env。如果以后把校验换成 URL、网段或多个字段，这个顺序仍然适用。

package main

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

type Config struct {
    Env string
}

func bindFlags(fs *flag.FlagSet, cfg *Config) {
    fs.Func("env", "运行环境：dev、staging 或 prod", func(raw string) error {
        // 先在局部变量中校验，失败时不修改现有配置
        env := raw
        switch env {
        case "dev", "staging", "prod":
            cfg.Env = env
            return nil
        default:
            return errors.New("env 只能是 dev、staging 或 prod")
        }
    })
}

func main() {
    cfg := Config{Env: "dev"} // 参数未提供时保留显式默认值
    fs := flag.NewFlagSet("deploy", flag.ContinueOnError)
    bindFlags(fs, &cfg)

    // Parse 会把回调错误作为参数解析错误返回
    if err := fs.Parse(os.Args[1:]); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(2)
    }
    fmt.Println("environment:", cfg.Env)
}

flag.Func 没有单独的默认值参数，所以默认值应在配置对象初始化时写清楚。回调只在用户实际提供该参数时触发。若参数允许重复，最后一次成功赋值会覆盖前一次；若不允许重复，可以在闭包中记录是否已经设置并返回明确错误。

把解析错误留给 FlagSet

顶层 flag.Parse 适合简单命令，但它使用默认命令行集合，错误处理不方便隔离。我在需要单元测试、子命令或复用解析逻辑时，会创建自己的 FlagSet。ContinueOnError 让 Parse 把错误交还调用方；ExitOnError 更适合边界很薄的独立命令；PanicOnError 通常只用于程序员错误明显、上层确实希望捕获 panic 的特殊场景。

错误文本要写用户可修复的信息，例如允许值、格式或范围。不要只返回“invalid value”，否则 flag 即使打印了参数名，用户仍不知道应该改成什么。

用表驱动测试覆盖边界

func TestEnvFlag(t *testing.T) {
    tests := []struct {
        name    string
        value   string
        wantErr bool
    }{
        {name: "生产环境", value: "prod"},
        {name: "未知环境", value: "preview", wantErr: true},
        {name: "空字符串", value: "", wantErr: true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            cfg := Config{Env: "dev"}
            fs := flag.NewFlagSet("test", flag.ContinueOnError)
            bindFlags(fs, &cfg)

            // 直接传参数切片，测试不依赖进程级 os.Args
            err := fs.Parse([]string{"-env", tt.value})
            if (err != nil) != tt.wantErr {
                t.Fatalf("Parse() error = %v, wantErr %v", err, tt.wantErr)
            }
            if tt.wantErr && cfg.Env != "dev" {
                t.Fatalf("校验失败后配置被修改为 %q", cfg.Env)
            }
        })
    }
}

除了合法值和非法值，还应覆盖参数缺省、重复出现、大小写约定及空白字符。我的取舍是让回调只承担单个参数的解析与局部校验，真正跨多个参数的业务约束仍放在 Parse 成功之后，这样错误归属更清楚。

flag.Func 和实现 flag.Value 有什么区别？

flag.Func 更适合一次性、局部的转换规则；需要复用类型、控制字符串展示或实现更复杂状态时，定义实现 flag.Value 的类型更清晰。

回调返回错误后还会进入业务逻辑吗？

取决于调用方是否检查 Parse 的结果。使用 ContinueOnError 时必须判断返回错误并停止后续业务；不要忽略它。