Go flag.TextVar 怎样把自定义类型接入命令行

命令行参数一旦不再是普通字符串，解析规则很容易散落在 main、配置读取和测试代码里。Go 的 flag.TextVar 适合把这件事收回到类型本身：让自定义类型实现 encoding.TextUnmarshaler，再把目标变量的指针交给 TextVar。这样参数到达时会调用同一个 UnmarshalText，非法输入也能沿着 FlagSet.Parse 返回。

一、先把命令行规则放回自定义类型

假设部署程序需要接收区域编码。命令行层只接收文本，哪些区域合法、是否允许空白、错误应该怎样返回，都由 Region 自己负责。解析成功后再修改接收者，失败时不要留下半成品。

package main

import (
	"fmt"
	"strings"
)

type Region string

func (r *Region) UnmarshalText(text []byte) error {
	// 先复制成字符串并清理空白，再只接受程序明确支持的区域。
	value := strings.TrimSpace(string(text))
	switch 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) {
	// 值接收者让自定义类型可以作为 TextVar 的默认值。
	return []byte(r), nil
}

UnmarshalText 使用指针接收者，是因为解析结果需要写回变量。方法里把传入字节转换为自己的字符串值；如果类型要在方法返回后继续保存原始字节，也应自行复制，不能依赖调用方后续仍持有同一块内存。

二、用 TextVar 把类型接入 FlagSet

接着创建一个独立的 FlagSet。这里使用 flag.ContinueOnError，让上层得到解析错误并决定如何提示，而不是让库代码直接结束进程。没有传入 -region 时保留默认值，传入后则进入同一个 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 类型。
	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)
}

注意第三个参数不是随便写的字符串，而是与目标类型匹配的文本默认值。把 string("cn-hz") 传给 *Region 会破坏类型契约；直接使用 Region("cn-hz") 更清晰，也能让帮助信息使用正确的默认表示。

三、把默认值和错误边界分开看

这里有三个容易混淆的时机。第一，注册 TextVar 时，目标必须是指针，默认值的类型必须和指针指向的类型一致。第二，没有参数时，程序应直接使用初始化好的默认值，并不会凭空产生一次业务解析。第三，参数出现后，文本交给 UnmarshalText；该方法返回的错误会成为 Parse 的错误。

如果命令程序只需要一次解析，通常在创建完所有 flag 后调用一次 Parse 即可。若测试或封装层要重复解析，建议每次使用新的 FlagSet，避免把上一次解析的状态和本次参数混在一起。

四、什么时候换成 Var 或 Func

一个简单判断是：离开命令行入口后，这套文本规则是否仍然有价值？如果环境变量、配置文件或接口参数也要接受同样格式，优先让类型实现 TextUnmarshaler，然后使用 TextVar。如果参数需要多次出现并累积到切片，或者展示字符串的方式与解析格式不同，flag.Var 更合适。

flag.Func 适合一次性处理：回调拿到文本后立即完成当前动作，规则没有必要沉淀为类型能力。它的代码可能更短，但不会自动为其他入口提供同一套解析契约。选择的重点不是 API 新旧，而是解析逻辑的复用范围。

常见问题

TextVar 为什么要求传指针？

因为 UnmarshalText 要把结果写回目标变量，标准库也明确要求 p 是持有结果的指针。

只有 UnmarshalText 没有 MarshalText 可以吗？

目标参数仍需实现 TextUnmarshaler；但默认值参数需要满足 TextMarshaler，实践中给同一个类型补齐 MarshalText 更稳妥。

非法参数应该在 main 里判断吗？

格式和取值范围属于类型规则，放进 UnmarshalText 更容易复用；main 只负责接住 Parse 的错误并决定提示方式。