Go flag.Value 实现自定义参数时如何报告非法输入

我在给命令行工具增加 -level 参数时，最容易写错的地方不是注册参数，而是把非法字符串直接写进配置，再在后面才发现值不对。flag.Value 的正确边界很清楚：Set(string) error 负责解析和校验，失败就返回错误，只有成功后才提交新值。

Set 不要只做赋值；它应该是一个小型的“字符串到合法状态”事务，失败时返回足够定位的错误。

为什么 flag.Value 的 Set 必须返回错误

flag.Value 由 String() string 和 Set(string) error 组成。解析器会按照命令行中出现的顺序调用 Set；只要它返回错误，错误就会回到 FlagSet.Parse，不会继续把这次设置当成成功结果。这里的返回值不是提示信息，而是参数输入契约的一部分。

因此，Set 里应当把外部字符串当成不可信输入。比如等级只允许 debug、info、warn 三个值，其他输入都应带着原始值返回，而不是静默回退到 info。静默回退会让启动参数看似生效，实际却运行在另一套配置上。

用临时值校验后再写入业务配置

下面的类型保存展示文本和内部整数值。关键点是先从映射表取出局部结果；查找失败时直接返回，接收者仍保持原状态。

package main

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

type levelValue struct {
    text  string
    value int
}

func (v *levelValue) String() string {
    // String 可能被帮助信息读取，空指针时返回安全的空文本。
    if v == nil {
        return ""
    }
    return v.text
}

func (v *levelValue) Set(s string) error {
    // 先解析到局部变量，非法输入不能覆盖当前配置。
    levels := map[string]int{"debug": 10, "info": 20, "warn": 30}
    parsed, ok := levels[s]
    if !ok {
        // 返回原始值和允许范围，调用方才能定位启动参数问题。
        return fmt.Errorf("level %q is invalid: want debug, info, or warn", s)
    }
    // 校验通过后一次性提交文本和值，保持两者一致。
    v.text, v.value = s, parsed
    return nil
}

func main() {
    fs := flag.NewFlagSet("demo", flag.ContinueOnError)
    level := &levelValue{text: "info", value: 20}
    // Var 把自定义 Value 挂到 -level 参数上。
    fs.Var(level, "level", "logging level")
    if err := fs.Parse(os.Args[1:]); err != nil {
        // ContinueOnError 让程序可以记录错误并由上层决定退出方式。
        fmt.Fprintln(os.Stderr, err)
        return
    }
    fmt.Println(level.text, level.value)
}

这里不要在解析前清空 v.text，也不要用“遇到未知值就取默认值”的分支。默认值应该在创建 levelValue 时确定；参数一旦出现，就必须明确成功或失败。

Parse 报错和手动 Set 如何分别处理

命令行运行时使用 fs.Parse，推荐配合 flag.ContinueOnError，让调用者获得可测试的错误返回。参数名未知、缺少值和 Value.Set 返回的非法输入，都会在这里汇总。不要只检查进程是否退出，还要把错误写入测试断言或启动日志。

配置文件、环境变量适配层或单元测试可以直接调用 fs.Set("level", raw)。它同样会走自定义 Set，所以校验规则只有一份：

安全上，这个小类型的资产就是“最终生效的配置”。输入边界是字符串，控制点是白名单校验，审计信息是原始值和返回错误。启动器在收到错误后应停止创建服务，或者明确走降级策略；不要让错误值带着默认配置继续运行。

把非法输入变成可定位的错误信息

错误至少应包含参数的语义名称、收到的值和允许范围。若值来自环境变量或配置文件，可在外层补充来源，但不要在 Set 内混入退出进程、打印日志或读取全局配置。这样同一个 Value 才能被命令行、测试和配置适配层复用。

常见问题

Set 返回错误后，旧值会不会被清空？

只要实现先校验、后赋值，旧值会保留；如果先赋值再解析，就需要额外回滚，通常更容易遗漏。

为什么还要实现 String？

String 用于默认值和帮助信息展示，也是 flag.Value 接口的一部分。指针接收者应考虑零值或空指针被读取的情况。

自定义 Value 能不能支持重复参数？

可以，解析器会按出现顺序多次调用 Set；是否允许覆盖、累加或拒绝重复，应在类型内部写成明确规则。