Go flag包存在四大隐式陷阱：一是flag.Parse()必须在所有flag定义之后且仅调用一次；二是StringSlice不自动合并多次参数，需自定义Value类型实现追加；三是自定义类型须完整实现flag.Value接口（Set和String方法）；四是help文本硬编码、不可配置，需手动拦截-h/--help并定制输出。
Go 的 flag 包足够轻量，但默认行为容易让人踩坑——比如不加 -h 就看不到帮助、字符串切片解析失败、自定义类型支持模糊。关键不是“能不能用”，而是“怎么避开隐式陷阱”。
flag.Parse() 必须在所有 flag 定义之后调用
这是最常被忽略的执行顺序问题：一旦在 flag.String() 等定义前调用了 flag.Parse()，所有参数都会被忽略，且不会报错，只会返回空值。
常见错误场景：
- 把
flag.Parse()放在main()开头，后面才定义 flag - 在 init 函数里提前调用
flag.Parse() - 多个包各自定义 flag，但主包未统一控制解析时机
正确做法是：所有 flag.Xxx() 调用必须在 flag.Parse() 之前，且仅调用一次。
立即学习“go语言免费学习笔记（深入）”；
字符串切片 flag.StringSlice 的坑：多次传参不自动合并
flag.StringSlice("tags", []string{}, "tag list") 看似支持多次使用，比如 ./app -tags a -tags b，但实际结果是 []string{"b"} —— 后面的值会覆盖前面的，而不是追加。
要实现真正的多值追加，必须手动注册自定义类型或改用 flag.StringSliceVar 配合 flag.Var：
type stringSlice []string
func (s *stringSlice) Set(value string) error {
*s = append(*s, value)
return nil
}
func (s *stringSlice) String() string {
return strings.Join([]string(*s), ",")
}
var tags stringSlice
flag.Var(&tags, "tags", "add tag (can be repeated)")
这样 -tags a -tags b 才会得到 []string{"a","b"}。
自定义 flag 类型必须实现 flag.Value 接口
想支持类似 -timeout 30s 这样的带单位解析？不能只靠 flag.Duration（它只认标准格式），得自己写类型。核心是实现两个方法：
-
Set(string) error：接收命令行原始字符串，解析并赋值 -
String() string：返回当前值的字符串表示（用于 help 输出）
例如解析带单位的时间字符串：
type durationFlag time.Duration
func (d *durationFlag) Set(s string) error {
t, err := time.ParseDuration(s)
if err != nil {
return fmt.Errorf("invalid duration %q", s)
}
*d = durationFlag(t)
return nil
}
func (d *durationFlag) String() string {
return time.Duration(*d).String()
}
var timeout durationFlag
flag.Var(&timeout, "timeout", "timeout with unit, e.g. 5s, 2m")
注意：flag.DurationVar 不支持这种自由格式；直接用 flag.Duration 则要求输入必须是 Go 标准格式（如 30s, 2m30s），不能是 30sec 或 2minutes。
help 文本不自动换行且无法关闭，-h 和 --help 是硬编码
flag.PrintDefaults() 输出的帮助文本是纯左对齐、无折行、无缩进的，且字段宽度固定为 24 字符。你不能通过配置关闭它，也不能改写 help 的触发逻辑——只要传入 -h 或 --help，就会打印后退出。
如果需要更友好的帮助信息（比如支持子命令、带示例、支持 Markdown 渲染），必须绕过默认行为：
- 在
flag.Parse()前检查os.Args是否含-h/--help - 手动输出定制 help 并调用
os.Exit(0) - 避免调用
flag.PrintDefaults()，改用模板或结构化字符串生成
否则，用户看到的 help 会混着你的自定义说明和 flag 自动拼出的丑陋对齐字段，很难维护。
flag 包的“简单”是假象，真正难的是边界处理：空值默认行为、重复参数语义、help 与业务逻辑耦合、类型转换失败时不给出具体提示。别迷信文档里的“一行搞定”，先跑通 -h、--help、空参数、非法输入这四条路径，再谈功能。
