Go flag.TextVar 怎么把命令行参数解析成自定义配置类型

如果命令行参数只是字符串，flag.String 足够了；但生产服务常见的重试策略、地址范围或带单位的配置，通常需要“解析 + 校验”两步。flag.TextVar 可以把这部分职责交给自定义类型：指针实现 encoding.TextUnmarshaler，默认值实现 encoding.TextMarshaler，解析成功后变量本身就是可用配置。

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

把命令行值解析成自定义类型的关键，不是给 flag 再包一层字符串，而是让类型自己的 UnmarshalText 负责格式、单位和范围检查；任何错误都原样进入 FlagSet.Parse 的错误路径。

先给配置格式画出边界

下面用一个重试策略作为例子。命令行写成 -retry=100ms,2s，逗号前是初始等待时间，逗号后是最大等待时间。这个格式足够短，既能放进启动参数，也能在日志中快速看懂。

文章只讨论标准库 flag 的文本转换，不引入第三方 CLI 框架。实现时还要明确两个业务约束：等待时间必须大于零，最大等待必须不小于初始等待。把约束写进类型，比在 main 中先读字符串再到处判断更容易复用。

让自定义类型自己完成解析和校验

encoding.TextUnmarshaler 只有一个方法：UnmarshalText([]byte) error。因此它很适合把“外部文本”转换成“内部结构”。下面的代码还实现了 TextMarshaler，这样同一类型可以表达默认值和帮助信息。

package main

import (
	"fmt"
	"strings"
	"time"
)

// RetryPolicy 保存重试等待时间，避免业务代码继续处理原始字符串。
type RetryPolicy struct {
	Initial time.Duration
	Max     time.Duration
}

// UnmarshalText 把 initial,max 文本转换为结构化配置并执行范围校验。
func (p *RetryPolicy) UnmarshalText(text []byte) error {
	parts := strings.Split(string(text), ",")
	if len(parts) != 2 {
		return fmt.Errorf("重试策略格式应为 initial,max，例如 100ms,2s")
	}

	initial, err := time.ParseDuration(strings.TrimSpace(parts[0]))
	if err != nil {
		return fmt.Errorf("初始等待时间无效: %w", err)
	}
	max, err := time.ParseDuration(strings.TrimSpace(parts[1]))
	if err != nil {
		return fmt.Errorf("最大等待时间无效: %w", err)
	}
	if initial 

这里使用指针接收者写入 RetryPolicy，因此注册时必须传 &policy。校验失败时不要先更新字段，调用方才能保证“解析失败就不产生半成品配置”。

用 TextVar 注册并解析

TextVar 的第三个参数不是字符串，而是与目标类型对应的 encoding.TextMarshaler 默认值。也就是说，默认值应使用同一个具体类型，不能随手传一段看似相同的字符串。

func parseFlags(args []string) (RetryPolicy, error) {
	fs := flag.NewFlagSet("worker", flag.ContinueOnError)
	defaultPolicy := RetryPolicy{
		Initial: 100 * time.Millisecond,
		Max:     2 * time.Second,
	}
	var policy RetryPolicy

	// TextVar 会把每次出现的 -retry 文本交给 policy.UnmarshalText。
	fs.TextVar(&policy, "retry", defaultPolicy, "重试等待，格式为 initial,max")
	if err := fs.Parse(args); err != nil {
		// ContinueOnError 让上层决定记录日志、打印帮助还是退出。
		return RetryPolicy{}, fmt.Errorf("解析命令行参数失败: %w", err)
	}
	return policy, nil
}

func main() {
	policy, err := parseFlags(os.Args[1:])
	if err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(2)
	}
	fmt.Printf("retry initial=%s max=%s\\n", policy.Initial, policy.Max)
}

完整示例需要补上 flag 和 os 导入。运行 -retry=500ms,3s 后，业务层直接读取两个 time.Duration 字段，不再关心文本如何切分。

把解析错误当成启动边界

解析失败不是业务运行中的可恢复异常。格式缺少逗号、单位拼错、最大值小于初始值，都应该在服务真正处理请求前暴露出来。flag.ContinueOnError 适合库函数、测试或需要自定义日志的命令；如果使用默认的 flag.CommandLine，也可以根据应用的退出策略选择对应行为。

func demoErrors() {
	// 格式错误：只有一个字段，UnmarshalText 返回自定义错误。
	_, err := parseFlags([]string{"-retry=2s"})
	if err != nil {
		fmt.Println("格式错误已拦截")
	}

	// 范围错误：最大等待比初始等待短，同样不会进入业务配置。
	_, err = parseFlags([]string{"-retry=2s,500ms"})
	if err != nil {
		fmt.Println("范围错误已拦截")
	}
}

如果参数来自部署系统，建议把原始参数、错误原因和退出码统一记录在启动日志中，但不要把包含敏感信息的整行命令无条件写入日志。对本例而言，日志记录“retry 参数格式错误”比记录所有启动参数更稳妥。

默认值、重复参数和选型边界

发布前可以按下面几项检查：

如果只需要接收一个字符串并执行一次轻量回调，flag.Func 会更直接；如果配置类型还需要被环境变量、JSON 或配置文件复用，保留 TextUnmarshaler 通常更划算。无论选哪种方式，都应让输入错误在启动边界返回，而不是把字符串解析推迟到请求处理路径。

相关问题

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

因为默认值参数要求实现 encoding.TextMarshaler，并且类型要与目标变量匹配。应传入同一自定义类型的值。

UnmarshalText 解析失败后会不会留下半个配置？

不会自动替你回滚，因此实现时应先解析到局部变量，全部校验通过后再一次性赋给接收者。

普通 duration 是否还需要自定义类型？

只接受一个标准 duration 时可使用 flag.DurationVar；只有在多个字段、特殊格式或额外范围约束出现时，才需要自定义类型。

参考资料

• https://pkg.go.dev/flag#TextVar
• https://pkg.go.dev/encoding#TextUnmarshaler
• https://go.dev/src/flag/flag.go