Go flag.TextVar 默认值为什么必须实现 TextMarshaler

用 flag.TextVar 注册自定义参数时，默认值不是随便传一个能打印的对象。它的参数类型本身要求实现 encoding.TextMarshaler，目标指针则要实现 encoding.TextUnmarshaler；同时，默认值解引用后的类型必须和目标指针指向的类型完全一致。前者负责把默认状态变成帮助文本，后者负责把命令行字符串解析回变量。

flag.TextVar 其实把解析和默认展示分成两条路径

TextVar 的四个参数里，p 是保存结果的目标，name 是参数名，value 是默认值，最后才是帮助说明。容易误解的地方在于：命令行传入的文本不会交给默认值的 MarshalText，而是交给 p.UnmarshalText；默认值主要影响变量初始化和 flag 的字符串表示。

标准库内部会先把默认值写入目标变量，再把目标包装成一个 flag.Value。这个包装的 Set 调用 UnmarshalText，String 则尝试调用目标的 MarshalText。因此，只实现反序列化而没有可用的序列化方法时，帮助中的默认值可能变成空字符串。

自定义类型要把两个方法安排在正确的接收者上

最稳妥的写法是让 UnmarshalText 使用指针接收者，因为解析过程要修改变量；MarshalText 可以使用值接收者，这样值和指针都能满足 TextMarshaler。下面的 Level 用固定值演示完整边界：

package main

import (
    "encoding"
    "errors"
    "flag"
    "fmt"
)

type Level string

// MarshalText 把当前值变成帮助文本和默认值文本。
func (l Level) MarshalText() ([]byte, error) {
    return []byte(l), nil
}

// UnmarshalText 只接受约定的级别，并把结果写回目标变量。
func (l *Level) UnmarshalText(data []byte) error {
    next := Level(string(data))
    if next != "info" && next != "debug" && next != "error" {
        return errors.New("level must be info, debug, or error")
    }
    *l = next
    return nil
}

// 编译期断言让接口职责在重构时立即暴露。
var _ encoding.TextMarshaler = Level("")
var _ encoding.TextUnmarshaler = (*Level)(nil)

func main() {
    level := Level("info")
    // 默认值与目标变量都使用 Level，命令行值由 UnmarshalText 解析。
    flag.TextVar(&level, "level", Level("info"), "运行级别")
    flag.Parse()
    fmt.Println(level)
}

没有传入 -level 时，目标变量先得到 info；传入 -level=debug 后，flag.Parse 调用 UnmarshalText 并将目标改为 debug。代码中的接口断言不是必须步骤，却能把“谁负责序列化、谁负责反序列化”固定下来。

默认值的类型必须和目标变量对齐

调用 TextVar(&level, "level", Level("info"), "运行级别") 时，p 的类型是 *Level，默认值的类型是 Level，两者去掉指针后相同。如果把默认值写成普通 string，即便文本内容看起来一样，也不满足参数类型；如果自定义类型只有指针接收者的 MarshalText，则默认值也要传指针。

标准库会在注册阶段检查这个关系：目标参数必须是指针，默认值如果是指针会先解引用，然后比较两边的类型。类型不一致时会直接 panic，所以不要把它当作运行时输入错误来捕获；正确做法是在定义 flag 时修正类型。

把解析错误交给 Parse，并检查帮助文本

UnmarshalText 应该只负责把一段文本转换成合法状态。返回错误后，flag.Parse 会按当前 FlagSet 的错误策略处理；不要在 main 里再写一套相同的字符串判断。调试自定义参数时，优先检查下面三项：

• 默认值的静态类型是否与目标变量一致，而不是只看文本是否相同。
• UnmarshalText 是否为指针接收者，并在失败时保留原值。
• MarshalText 是否能返回稳定、简短的默认表示，让 -h 输出可读。

如果类型复杂到需要外部资源、多个字段或多种输入格式，仍可使用 flag.Value 自定义 Set 和 String。TextVar 更适合已经具备文本编解码边界的类型：接口职责清楚，帮助文本和命令行解析也能复用同一套规则。

常见问题

TextVar 的默认值为什么不能直接传字符串？

因为参数静态类型是 encoding.TextMarshaler，普通字符串没有实现该接口；并且标准库还要求默认值的类型与目标变量类型匹配。

只实现 UnmarshalText 能不能解析参数？

命令行输入可以进入解析方法，但默认值的字符串表示可能为空。要让帮助输出和 flag 的默认展示稳定，目标类型还应提供可用的 MarshalText。

什么时候应该改用 flag.Value？

当参数的文本格式不适合 encoding.TextMarshaler/TextUnmarshaler，或需要更细的 Set、String 行为时，直接实现 flag.Value 会更直观。