Go 命令行 flag 怎么把重复参数收集成切片

Go 的 flag.String 适合“一个参数对应一个字符串”。如果命令需要这样调用：-tag api -tag worker -tag retry，最小且可控的做法是定义一个字符串切片类型，让它实现 flag.Value，并在 Set(string) error 中追加元素。flag.Var 注册后，解析器每遇到一次 -tag，就会再次调用同一个值对象的 Set。

重复参数能否收集，不是 flag 自动替你决定的；只要自定义 Value 的 Set 按需 append，就能保留每次传入的顺序，同时把非法值通过返回错误交回解析流程。

flag.Value 的 Set 为什么能收集重复参数

普通字符串 flag 通常把解析结果放进一个变量；重复赋值时，调用方很难表达“保留全部值”。flag.Value 的思路是把解析动作交给对象：String 用于描述当前值，Set 接收解析到的文本。切片类型本身就是容器，所以 Set 只需把当前文本追加进去。

这里要使用指针接收者。Set 需要修改切片头部的长度和底层数组；如果使用值接收者，修改的只是副本。String 则服务于帮助信息和诊断，返回一个稳定、可读的表示即可。

package main

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

// stringList 是允许重复出现的命令行参数容器。
type stringList []string

// String 让 flag 能在帮助或错误信息中展示当前值。
func (s *stringList) String() string {
    if s == nil {
        return ""
    }
    return strings.Join(*s, ",")
}

// Set 每被解析到一次就追加一个值，顺序与命令行保持一致。
func (s *stringList) Set(value string) error {
    if strings.TrimSpace(value) == "" {
        return fmt.Errorf("tag 不能为空")
    }
    *s = append(*s, value)
    return nil
}

func main() {
    var tags stringList
    // Var 把同一个切片对象交给 flag，重复 -tag 会重复调用 Set。
    flag.Var(&tags, "tag", "可重复传入的标签")
    flag.Parse()
    fmt.Println(tags)
}

这个实现把“一次参数对应一个元素”写得很明确。Set 只校验空白并追加原字符串，没有偷偷按逗号拆分，因此 -tag "api,v2" 仍然是一个元素。若产品契约希望逗号代表多个标签，应在这里明确拆分并逐项校验，而不是让调用者猜。

注册与解析：重复参数和位置参数要分开

注册完成后调用 flag.Parse()。例如命令行为 tool -tag api -tag worker config.yaml，tags 得到 []string{"api", "worker"}，而 flag.Args() 得到 []string{"config.yaml"}。重复 flag 是已声明参数的值，文件名等剩余内容则属于位置参数。

当 Set 返回错误时，解析不会把这个值当作成功输入。错误信息应说明哪个值不合规，避免在业务层才发现切片里混入空字符串。对于需要可测试错误的程序，可以使用 flag.NewFlagSet 和 flag.ContinueOnError，让调用方拿到解析错误，而不是直接退出。

默认值、空值与错误：先固定参数契约

声明时可以先给切片一个默认值，例如 tags := stringList{"default"}，然后再用 flag.Var(&tags, ...)。此时重复参数会继续追加；如果业务语义是“用户一旦传入就替换默认值”，就需要在类型中增加一次性状态，第一次 Set 时清空默认项。这个选择必须写在帮助文案或文档里。

空值也有两种来源：用户传入 -tag=，或传入只含空白的文本。是否允许它们取决于业务，但最好由 Set 统一判断。不要在 Parse 之后再过滤，因为那会丢失原始错误位置，也可能让“用户没传标签”和“传了空标签”变成同一个状态。

// Set 的错误返回会被 flag 当作值解析错误处理。
func (s *stringList) Set(value string) error {
    value = strings.TrimSpace(value)
    if value == "" {
        return fmt.Errorf("tag 不能为空")
    }
    if len(value) > 32 {
        return fmt.Errorf("tag 过长")
    }
    *s = append(*s, value)
    return nil
}

一次一个元素还是逗号列表：不要让调用方式失去一致性

重复参数和逗号列表都能得到切片，但它们的使用体验不同。-tag api -tag worker 更容易保留顺序、定位哪个输入失败，也便于脚本按数组参数传递；-tag api,worker 更短，却需要定义转义、空元素和逗号出现在合法名称中的处理。对于面向自动化脚本的 CLI，我通常优先选择一次一个元素，只有已有用户习惯逗号配置时才增加拆分。

落地前可以按这张清单检查：类型是否用指针接收者；Set 是否真正 append；非法值是否返回 error；重复值是否保序；位置参数是否从 Args 读取；帮助信息是否说明参数可重复。这样扩展参数数量时，调用方不会从“最后一个值”突然变成不可预测的混合格式。

常见问题

同一个 flag 重复传入时，Set 会被调用几次？

通常每解析到一次该 flag 就调用一次 Set，因此切片追加次数与参数出现次数对应。

为什么 String 方法不能省略？

flag.Value 要求同时提供 String() string 和 Set(string) error。String 还会用于诊断和展示默认值，返回空字符串比输出内部指针更合适。

能不能直接把 []string 传给 flag.Var？

原生 []string 没有实现所需方法，不能直接传入；可以定义一个命名类型，再给它增加方法。

重复参数与位置参数的顺序会互相影响吗？

flag 遇到第一个非 flag 参数后会停止继续解析 flag。需要把所有 -tag 放在位置参数前面，并用 Args 读取剩余参数。