Go flag 包如何支持重复参数：自定义 flag.Value、切片收集与参数校验

命令行工具一旦需要接收多个标签、多个文件或多个后端地址，单个字符串参数很快就不够用了。Go 标准库的 flag 没有直接提供“同名参数自动收集为切片”的注册函数，但 flag.Value 正好可以把每次解析到的值追加起来，同时在入口处拒绝空值和非法格式。

把重复参数定义成一个实现了 flag.Value 的切片类型，再把它交给 Var；命令行中每出现一次参数，Set 就被调用一次。

先看默认单值参数为什么不够

flag.String 返回的是一个指针，后出现的同名参数不会自然形成切片。要让调用方写出可读的命令，常见形式是：

go run . --tag=go --tag=web --tag=cli

这类输入的关键不是“把字符串再拆一次”，而是保留参数出现的顺序，并在每次出现时独立校验。这样用户看到的错误能明确指向哪一个值，而不是等解析结束后才面对一串难定位的文本。

实现一个可复用的重复参数类型

package main

import (
    "errors"
    "flag"
    "fmt"
    "strings"
)

type stringList []string

func (s *stringList) String() string {
    return strings.Join(*s, ",")
}

func (s *stringList) Set(value string) error {
    value = strings.TrimSpace(value)
    if value == "" {
        return errors.New("tag cannot be empty")
    }
    *s = append(*s, value)
    return nil
}

func main() {
    var tags stringList
    flag.Var(&tags, "tag", "repeatable tag")
    flag.Parse()

    if len(tags) == 0 {
        fmt.Println("at least one --tag is required")
        return
    }
    fmt.Printf("tags=%q\n", []string(tags))
}

这里的 String 主要服务于帮助信息、调试和默认值展示；真正收集参数的是 Set。指针接收者很重要，否则追加只会发生在方法内部的副本上。

注册方式决定了每次输入都会进入 Set

flag.Var(&tags, "tag", "repeatable tag") 把参数名和自定义值绑定起来。解析器每读到一个 --tag，都会把等号后的内容交给 Set，因此以下命令最终保持输入顺序：

go run . --tag=go --tag=web --tag=cli
# tags=["go" "web" "cli"]

短横线形式也可以使用：-tag go -tag web。如果参数来自脚本，推荐统一采用等号形式，阅读日志时更容易看出键和值的边界。

把语法错误和业务检查分开

Set 负责当前值是否合法

空字符串、前后空格、明显不符合格式的值，都适合在 Set 中处理。返回错误后，flag.Parse 会停止解析并输出错误，不会把坏值放进切片。

func (s *stringList) Set(value string) error {
    value = strings.TrimSpace(value)
    if value == "" {
        return errors.New("tag cannot be empty")
    }
    if strings.ContainsAny(value, "\t\n") {
        return fmt.Errorf("tag contains control whitespace: %q", value)
    }
    *s = append(*s, value)
    return nil
}

Parse 后负责整体条件

“至少传一个标签”“不能超过 8 个标签”属于整体规则，应在 Parse 成功后检查。这样错误信息不会混淆单个参数格式和整个命令的业务要求。

if len(tags) == 0 {
    fmt.Fprintln(flag.CommandLine.Output(), "at least one --tag is required")
    return
}
if len(tags) > 8 {
    fmt.Fprintln(flag.CommandLine.Output(), "at most 8 --tag values are allowed")
    return
}

从单值模型迁移时要注意三个边界

第一，旧代码可能把空字符串当成“没有配置”，而重复参数类型通常应该直接报错，否则一个无效值会悄悄进入下游请求。第二，切片是否允许重复要先定规则；如果标签重复没有意义，可以在业务层用 map 去重，但不要在 Set 中擅自改变用户输入顺序。第三，flag.Parse 只处理它能看到的参数，位置参数仍会留在 flag.Args() 中，不能误认为它们也是 --tag 的值。

用 FlagSet 做可测试的参数入口

程序变大后，不建议让测试直接改全局 flag.CommandLine。单独创建 FlagSet，把输出导向缓冲区，就能稳定验证正常输入和错误输入：

func parseTags(args []string) (stringList, error) {
    fs := flag.NewFlagSet("demo", flag.ContinueOnError)
    fs.SetOutput(io.Discard)

    var tags stringList
    fs.Var(&tags, "tag", "repeatable tag")
    if err := fs.Parse(args); err != nil {
        return nil, err
    }
    if len(tags) == 0 {
        return nil, errors.New("at least one --tag is required")
    }
    return tags, nil
}

上面的示例如果放进完整项目，需要补上 io 导入。测试时可以分别传入两个 --tag、空值和未知参数，检查返回错误而不是依赖终端输出文本。

常见问题

同一个参数可以出现多次吗？

可以，但前提是注册的是实现 flag.Value 的类型。使用 flag.String 时不要期待它自动返回切片。

应该在 String 方法里拼接参数吗？

不应该。String 只负责当前值的字符串表示，收集动作放在 Set；否则帮助信息或调试调用可能意外改变状态。

参数顺序会保留吗？

只要 Set 直接追加到切片，顺序就会保留。如果后续用 map 去重，应该把去重放在明确的业务阶段，并写清是否保持第一次出现的位置。

小结

重复参数的核心是让参数类型拥有状态：每次解析调用一次 Set，每次成功就追加一个值。把单值格式校验放进 Set，把数量和必填条件放在解析完成后，迁移成本小，错误边界也清楚。