Go flag.TextVar 怎么复用 encoding.TextUnmarshaler

flag.TextVar 的用法可以概括成一句话：把“字符串转成领域类型”的规则放进 UnmarshalText，再让命令行解析器调用它。这样参数、JSON 配置甚至其他文本入口都能复用同一套校验，不必再为 flag.Value 单独实现 Set 和 String。

官方文档：https://pkg.go.dev/flag#TextVar、https://pkg.go.dev/encoding#TextUnmarshaler

先看清 TextVar 的三个角色

我最初看到 TextVar 的签名时，容易把两个接口混在一起。实际上职责很清楚：TextUnmarshaler 负责接收用户输入，TextMarshaler 负责把默认值表示成文本，TextVar 只负责把它们接到 flag。官方文档还明确要求目标参数是指针；只有这样，UnmarshalText 才能把解析结果写回变量。

这套 API 从 Go 1.19 起提供。如果项目必须兼容更早的 Go 版本，就继续使用 flag.Var 或 flag.Func；否则，已有文本协议的类型通常优先接 TextVar。

把解析与校验集中到 LogLevel

下面定义一个日志级别类型。关键做法是先把输入解析到局部变量，确认合法后再赋值。这样 debug、INFO 等输入会被统一成小写，而非法值不会覆盖原有配置。

type LogLevel string

const (
    LevelDebug LogLevel = "debug"
    LevelInfo  LogLevel = "info"
    LevelWarn  LogLevel = "warn"
    LevelError LogLevel = "error"
)

func (l *LogLevel) UnmarshalText(text []byte) error {
    // 先规范化到局部变量，校验通过后再写回接收者
    next := LogLevel(strings.ToLower(strings.TrimSpace(string(text))))
    switch next {
    case LevelDebug, LevelInfo, LevelWarn, LevelError:
        *l = next
        return nil
    default:
        return fmt.Errorf("unsupported log level %q", text)
    }
}

func (l LogLevel) MarshalText() ([]byte, error) {
    // 默认值和帮助信息使用与输入协议相同的文本形式
    return []byte(l), nil
}

UnmarshalText 收到的字节只在方法调用期间有效；如果类型需要保存原始字节，就必须复制。这里最终保存的是新建字符串对应的 LogLevel，不会持有传入切片。

接入 TextVar，并保留可回滚的错误边界

func main() {
    level := LevelInfo

    // 目标变量与默认值都是 LogLevel；指针只用于接收解析结果
    flag.TextVar(&level, "level", LevelInfo, "log `debug|info|warn|error`")
    flag.Parse()

    fmt.Printf("level=%s\n", level)
}

执行 go run . -level warn 后，业务代码拿到的是 LogLevel，不再需要第二次字符串校验。如果传入 -level trace，UnmarshalText 返回的错误会被 flag 当作参数值错误处理。使用默认的 flag.CommandLine 时，这类错误会打印用法并退出；库代码或测试中更适合创建 flag.NewFlagSet(..., flag.ContinueOnError)，由调用者决定回滚、提示还是重试。

同一解析规则还能复用到 JSON

encoding 包定义这些接口的目的，就是让一个类型被多个编码器复用。对于 JSON 字符串字段，encoding/json 也能调用 UnmarshalText，因此配置文件和命令行会共享相同的大小写规范、允许值和错误文本。

type Config struct {
    Level LogLevel `json:"level"`
}

var cfg Config
// JSON 字符串会复用 LogLevel.UnmarshalText 的校验规则
if err := json.Unmarshal([]byte(`{"level":"WARN"}`), &cfg); err != nil {
    return err
}

上线前我会固定检查四类情况：合法值能否写入、大小写和空格是否按约定规范化、非法值是否保留旧值、默认值能否正确出现在帮助信息中。若某个入口需要不同语法，就不要在 UnmarshalText 里偷偷加例外，而应为该入口单独包装，避免通用文本协议逐渐失控。

只实现 UnmarshalText 可以吗？

不能直接满足 TextVar 的完整参数要求，因为默认值还要通过 TextMarshaler 表示。若不需要复用默认值展示，可考虑 flag.Func。

为什么不直接使用 flag.Func？

一次性参数很适合 flag.Func；但同一类型还要进入 JSON、XML 或其他文本配置时，把规则放进类型本身更容易保持一致。

UnmarshalText 能修改一半再返回错误吗？

接口没有禁止，但这会让失败后的变量状态难以判断。更稳妥的做法是先解析到临时值，全部检查通过后再一次性赋值。