Go flag.TextVar 怎样复用类型的文本解析逻辑

如果命令行参数最终要落到一个有规则的 Go 类型里，flag.TextVar 可以直接复用这个类型的文本解析逻辑。做法是让目标类型实现 encoding.TextUnmarshaler，再把目标变量的指针传给 TextVar；参数出现时，标准库会把字符串交给 UnmarshalText。这样解析规则不会散落在命令行入口、配置加载器和测试代码里。

一、先把文本解析职责放回自定义类型

以部署区域为例，命令行只负责接收文本，合法值、空白处理和错误信息应该由 Region 自己决定。UnmarshalText 使用指针接收者，是因为解析成功后要修改目标变量；MarshalText 使用值接收者，便于把默认值交给 TextVar。

package main

import (
	"fmt"
	"strings"
)

type Region string

func (r *Region) UnmarshalText(text []byte) error {
	// 统一去掉输入两端空白，再限制可部署的区域编码。
	switch value := strings.TrimSpace(string(text)); value {
	case "cn-hz", "us-va":
		*r = Region(value)
		return nil
	default:
		return fmt.Errorf("unsupported region %q", value)
	}
}

func (r Region) MarshalText() ([]byte, error) {
	// 值接收者让 Region 的默认值可以作为 TextMarshaler 传入。
	return []byte(r), nil
}

二、用 TextVar 绑定默认值和参数变量

接下来用独立的 FlagSet 绑定变量。这里选择 flag.ContinueOnError，便于上层拿到错误而不是让标准库直接退出进程。没有传 -region 时，变量保留 cn-hz；传入参数后，TextVar 会调用同一个 UnmarshalText。

package main

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

func parseRegion(args []string) (Region, error) {
	fs := flag.NewFlagSet("deploy", flag.ContinueOnError)
	fs.SetOutput(os.Stdout)
	region := Region("cn-hz")
	// 复用 Region 的文本解析，不在命令行层重复写 switch。
	fs.TextVar(®ion, "region", region, "deployment region")
	if err := fs.Parse(args); err != nil {
		// 非法区域会沿着 Parse 返回，调用方可以决定如何提示或退出。
		return "", err
	}
	return region, nil
}

func main() {
	region, err := parseRegion(os.Args[1:])
	if err != nil {
		fmt.Println("parse flags:", err)
		return
	}
	fmt.Println("region:", region)
}

这里的关键不是把字符串变成结构体，而是把入口和类型解耦：环境变量、配置文件或测试若也采用同一文本格式，可以继续调用同一个解析方法。

三、默认值和错误边界要提前定好

TextVar 的第三个参数不是任意字符串，而是 encoding.TextMarshaler。标准库会检查传入的 p 是指针，并检查默认值的实际类型是否等于目标指针指向的类型；不匹配会在注册阶段触发 panic。因此不要把 string 默认值传给 *Region，直接使用 Region("cn-hz")。

解析失败时，UnmarshalText 返回的错误会成为 flag 的参数解析错误。解析器最好先校验，再修改接收者，避免一个失败参数把目标变量写成半成品。若同一个 FlagSet 被重复调用 Parse，还应把它当作新的解析生命周期管理，常规命令行程序通常只解析一次。

四、按复用范围选择 TextVar、Var 或 Func

TextVar 适合“一个类型有明确文本表示”的情况，例如 IP、时间或业务编码。若参数允许重复出现并且要累积到切片，或者需要让 String 展示特殊格式，flag.Var 更直接。若只是把一个字符串交给一次性业务回调，flag.Func 的代码更短，但解析规则不会自然沉淀成类型能力。

一个实用判断是：离开命令行后，这段文本解析是否仍然有价值？答案是“有”，优先实现 TextUnmarshaler；答案是“没有”，再考虑 Func。这能避免为了注册一个 flag 而制造一套只在 main 函数里可见的转换逻辑。

常见问题

TextVar 为什么要求传指针

因为 UnmarshalText 要把解析结果写回变量。传值无法稳定改变调用方持有的值，标准库也会在内部检查参数必须是指针。

只有 UnmarshalText 没有 MarshalText 能不能用

目标参数仍可实现文本解码，但默认值参数的静态类型必须满足 TextMarshaler。实践中给类型补上对称的 MarshalText，帮助信息和默认值展示会更稳定。

什么时候不该用 TextVar

当一次参数需要累积多个值、依赖命令行上下文，或格式只服务当前回调时，Var 或 Func 会更贴合；不要为了使用新 API 强行改造没有复用价值的解析逻辑。