go-flags比标准库flag更适配复杂CLI场景，因其支持嵌套结构、子命令、自动help生成、丰富类型转换及结构体标签驱动，避免手动注册和类型断言。
为什么不用 flag 标准库而选 go-flags
Go 标准库 flag 能干活，但对嵌套结构、子命令、自动生成帮助文本、类型自动转换（比如 []string 或 time.Duration）支持弱。go-flags 用结构体标签驱动，天然适配复杂 CLI 场景，比如服务启停带配置文件路径、环境模式、监听地址等多层参数组合。
它还能直接绑定到 struct 字段，避免手动调用 flag.String()、flag.Int() 一堆重复代码，也省去后续类型断言或转换的麻烦。
初始化 go-flags 并解析到结构体
核心是定义一个结构体，用 go-flags 支持的 tag 控制参数行为，再用 go-flags.Parse() 绑定。注意：结构体字段必须导出（首字母大写），否则解析失败且无报错。
-
short：单字符缩写，如h对应-h -
long：完整参数名，如config对应--config -
description：用于生成 help 文本 -
required：设为"true"表示必填（字符串值，不是布尔） -
env：指定环境变量名，如env:"APP_ENV"，会优先读取环境变量
示例：
立即学习“go语言免费学习笔记（深入）”；
type Options struct {
ConfigFile string `short:"c" long:"config" description:"Config file path" env:"CONFIG_PATH" required:"true"`
Mode string `short:"m" long:"mode" description:"Run mode: dev/prod" default:"dev"`
Port int `long:"port" description:"HTTP port" default:"8080"`
Debug bool `short:"d" long:"debug" description:"Enable debug logging"`
}
var opts Options
parser := flags.NewParser(&opts, flags.Default)
if _, err := parser.Parse(); err != nil {
if flagsErr, ok := err.(*flags.Error); ok && flagsErr.Type == flags.ErrHelp {
os.Exit(0)
}
log.Fatal(err)
}
支持子命令（比如 migrate up / migrate down）
go-flags 子命令本质是嵌套结构体，每个子命令对应一个字段，类型为指针（*SubCmd），并打上 command tag。主结构体不加 command，只做顶层入口。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
常见坑：Parse() 返回的 subcmd 是实际命中的子命令名（如 "up"），需手动判断执行逻辑；子命令结构体字段同样要导出，且不能有冲突的 long 名（比如两个子命令都用 long:"verbose" 会 panic）。
示例片段：
type MigrateCmd struct {
Up *UpCmd `command:"up" alias:"u" description:"Apply migrations"`
Down *DownCmd `command:"down" alias:"d" description:"Rollback last migration"`
}
type UpCmd struct {
Steps int `long:"steps" description:"Number of migrations to apply" default:"1"`
}
type DownCmd struct {
Steps int `long:"steps" description:"Number of migrations to rollback" default:"1"`
}
var cmds MigrateCmd
parser := flags.NewParser(&cmds, flags.Default)
subcmd, err := parser.Parse()
if err != nil {
log.Fatal(err)
}
switch subcmd {
case "up":
runUp(cmds.Up.Steps)
case "down":
runDown(cmds.Down.Steps)
}
与 viper 配置合并时的优先级陷阱
很多 Go 服务同时用 go-flags 解析命令行 + viper 加载配置文件 + 环境变量。三者优先级通常是：命令行 > 环境变量 > 配置文件。但 go-flags 的 env tag 默认只在 flag 未设置时读取，不会覆盖已设值 —— 这和 viper 的 AutomaticEnv() 行为不一致。
解决办法：要么统一用 go-flags 处理全部（包括从 config 文件加载后 merge 到 struct），要么显式控制顺序。推荐做法是先用 go-flags 解析，再用 viper.SetConfigFile(opts.ConfigFile) 加载配置，最后用 viper.Unmarshal() 覆盖 struct 默认值 —— 但要注意，viper 不会识别 go-flags 的 env tag，得自己调 viper.AutomaticEnv() 并设前缀。
容易漏掉的一点：go-flags 不支持 YAML 锚点、内联 map 等高级语法，如果配置文件用了这些，viper 能解析，go-flags 不能直接 load，别混用解析目标。
