Go flag 怎样为自定义类型实现 Value

Go 标准库的 flag 已经提供了字符串、整数、布尔值等常见参数类型，但业务参数经常不是一个简单的标量，例如 host:port、逗号分隔的标签或带范围限制的枚举值。这时可以实现 flag.Value，再用 flag.Var 把自定义类型接入解析器。

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

自定义 Value 的核心只有两个方法：String 负责把当前值表示成字符串，Set 负责把命令行传入的字符串解析并写回对象。真正的格式校验应该放在 Set 中，失败就返回错误，让 flag.Parse 停在参数边界上。

• 接口实现通常使用指针接收者，否则 Set 修改的可能只是副本。
• 注册自定义值使用 flag.Var 或 FlagSet.Var，不能直接套用 StringVar。
• 非法输入应返回带上下文的错误，不要悄悄保留半解析状态。
• 是否允许同一参数出现多次，要在类型设计中明确。

Value 接口到底要实现什么

官方 flag.Value 接口由 String() string 和 Set(string) error 组成。flag.Var 会把实现了该接口的对象交给参数解析器：参数出现时调用 Set；帮助信息和诊断需要展示默认值时调用 String。

Set 的输入永远是字符串，所以它既是格式转换入口，也是最适合做边界校验的地方。方法使用指针接收者，才能把解析后的结果写入命令行程序后续真正读取的变量。

用 host:port 定义一个自定义参数

下面定义一个监听地址类型。它只接受一个主机和一个 1 到 65535 之间的端口，校验范围是业务约束，不是 flag 包自动提供的规则。

package main

import (
    "errors"
    "fmt"
    "net"
    "strconv"
    "strings"
)

// ListenAddr 保存命令行解析后的监听地址。
type ListenAddr struct {
    Host string
    Port int
}

// String 为帮助信息和错误诊断提供稳定的默认值表示。
func (a *ListenAddr) String() string {
    if a == nil || a.Host == "" || a.Port == 0 {
        return "127.0.0.1:8080"
    }
    return net.JoinHostPort(a.Host, strconv.Itoa(a.Port))
}

// Set 解析 host:port，并在写回对象前完成所有输入校验。
func (a *ListenAddr) Set(raw string) error {
    host, portText, err := net.SplitHostPort(raw)
    if err != nil {
        return fmt.Errorf("监听地址必须是 host:port：%w", err)
    }
    // 端口先转成整数，再检查业务允许的范围。
    port, err := strconv.Atoi(portText)
    if err != nil || port  65535 {
        return errors.New("端口必须是 1 到 65535 之间的整数")
    }
    if strings.TrimSpace(host) == "" {
        return errors.New("主机名不能为空")
    }
    // 所有字段通过校验后再一次性写入，避免留下半更新状态。
    a.Host, a.Port = host, port
    return nil
}

这里先把文本解析到局部变量，最后才更新 ListenAddr。即使输入错误，也不会把旧的主机改掉、端口却还保留旧值。net.SplitHostPort 还可以处理带方括号的 IPv6 地址。

通过 flag.Var 注册并解析

实现接口后，使用 flag.Var(&addr, "listen", "监听地址") 注册。默认值来自对象当前状态，命令行传入 -listen 后才会触发 Set。解析完成前不要读取最终业务值。

func main() {
    var addr ListenAddr
    // 注册自定义 Value；默认展示由 addr.String() 决定。
    flag.Var(&addr, "listen", "监听地址，格式为 host:port")
    flag.Parse()

    // Parse 返回后，addr 已经是经过 Set 校验的业务值。
    fmt.Printf("listen=%s host=%s port=%d", addr.String(), addr.Host, addr.Port)
    fmt.Printf(" 剩余参数=%v", flag.Args())
}

调用示例：

# 传入 IPv4 地址，并把最后一个参数留给业务层。
go run . -listen 0.0.0.0:9000 input.txt

此时 flag.Args() 只包含非 flag 参数。解析器允许单短横线或双短横线形式；自定义值仍然以字符串作为输入。

Set 方法怎样做输入校验

Set 既接收用户输入，也承担错误边界。校验失败时直接返回错误，flag 会把它包装成无效参数提示。不要先写入结构体、再在后面发现格式不对，否则错误恢复会变得困难。

可以把 Set 的实现分成三层：

1. 语法层：能否拆出需要的字段，例如 host:port 是否完整。
2. 类型层：字段能否转换成目标类型，例如端口能否转换成整数。
3. 业务层：转换后的值是否满足范围、非空和组合约束。

错误信息要指出输入格式和失败原因。这样命令行用户不用重新阅读源码，就能知道应该怎样修正参数。

要不要允许同一参数设置多次

flag 可以多次看到同一个自定义参数，因此是否覆盖、追加或拒绝重复，要由 Set 明确决定。监听地址通常只允许一个值，可以加一个状态位阻止重复设置。

type SingleAddr struct {
    ListenAddr
    set bool
}

// Set 只允许设置一次，避免后一个参数静默覆盖前一个参数。
func (a *SingleAddr) Set(raw string) error {
    if a.set {
        return errors.New("--listen 只能设置一次")
    }
    var parsed ListenAddr
    // 先解析到临时对象，成功后再提交并标记状态。
    if err := parsed.Set(raw); err != nil {
        return err
    }
    a.ListenAddr = parsed
    a.set = true
    return nil
}

如果业务参数本来就是列表，例如多个 CIDR 或多个标签，那么可以在 Set 中追加到切片；关键是先决定重复参数的语义，并在帮助文本中说清楚。

Value、Func 和 TextVar 怎么选

如果这个值会出现在多个命令或配置入口，优先把解析逻辑放进自定义类型，再用 flag.Var 绑定。若只在一个命令里处理一次简单字符串，Func 往往更直接。

发布前的参数检查清单

• Value 是否由指针实现，Set 是否真的写回目标对象？
• Set 是否先校验、后提交，避免留下半更新状态？
• 非法输入是否返回了包含格式和原因的 error？
• 重复参数是覆盖、追加还是拒绝，帮助文本是否与实现一致？
• 默认值的 String 表示能否让用户看懂？

常见问题

为什么 Set 用值接收者时参数没有生效？

值接收者拿到的是副本，修改副本不会更新 main 中保存的对象。需要用指针接收者实现 Set，并把指针传给 flag.Var。

String 方法只用于打印吗？

它主要用于默认值展示和诊断文本。应返回稳定、可读且不泄露敏感信息的表示，不要把临时调试字段拼进去。

解析失败后还能继续运行吗？

使用默认命令行集合时，错误处理策略可能直接退出；自定义 FlagSet 并选择 ContinueOnError 可以由调用方接收错误，再决定是否继续。无论采用哪种策略，都不应忽略 Parse 的错误结果。

自定义 Value 能处理布尔开关吗？

可以进一步实现 IsBoolFlag() bool 并返回 true，让解析器把没有显式值的 -name 按 true 处理；只有确实需要开关语义时才这样设计。