go-flags 更适合复杂 cli，因其原生支持结构体绑定、嵌套子命令、自动帮助生成、类型校验及短/长选项组合；而标准 flag 包需手动管理 flagset、拼接帮助、处理 panic，且不支持字段级默认值或验证钩子。
go-flags 为什么比标准 flag 包更适合复杂 CLI
因为 go-flags 原生支持结构体绑定、嵌套子命令、自动帮助生成、类型校验和短/长选项组合，而标准 flag 包需要手动管理 FlagSet、拼接帮助文本、处理重复定义 panic，且不支持字段级默认值或验证钩子。
典型场景下，当你需要 ——
- 一个
--config参数同时支持-c短写和--config=file.yaml长写 - 子命令如
app serve --port=8080和app migrate --dry-run各自拥有独立参数集 - 某个
--timeout字段必须是正整数，否则提前报错退出 - 用户输入
-h或--help时，自动显示带缩进、分组、示例的格式化帮助
—— 这些都不是标准 flag 包开箱即用的能力，但 go-flags 只需几行结构体标签就能实现。
结构体字段声明必须首字母大写才能被解析
go-flags 使用反射读取结构体字段，如果字段名小写（如 port int），反射无法访问，该字段会被完全忽略，也不会出现在帮助里，更不会绑定参数值——这是最常踩的坑，且无任何编译或运行时提示。
正确写法：
type ServeOptions struct {
Port int `short:"p" long:"port" description:"HTTP server port" default:"8080"`
Host string `short:"H" long:"host" description:"Bind host" default:"localhost"`
Verbose bool `short:"v" long:"verbose" description:"Enable verbose logging"`
}
注意点：
- 所有字段必须是导出字段（首字母大写）
-
default:标签值会直接用于初始化，不是字符串模板；若字段是切片或 map，需用 JSON 语法（如default:"[\"a\",\"b\"]"） - 未加
description的字段不会出现在帮助中，但依然可被解析（不推荐） - 布尔字段不支持
default:"true"这类字符串赋值，只能写default:"1"或留空（默认 false）
子命令必须用嵌套结构体 + command 标签声明
go-flags 不靠 os.Args[1] 手动 switch，而是通过结构体字段上的 command 标签识别子命令。它会自动路由、解析并调用对应子命令的 Execute 方法。
示例：
type CLI struct {
Serve ServeOptions `command:"serve" alias:"s" description:"Start HTTP server"`
Migrate MigrateOptions `command:"migrate" alias:"m" description:"Run database migrations"`
}
type ServeOptions struct {
Port int `long:"port" default:"3000"`
}
func (x *ServeOptions) Execute(args []string) error {
fmt.Printf("serving on :%d\n", x.Port)
return nil
}
关键规则：
- 主结构体字段必须是结构体类型，且含
command:标签；普通字段（如Version string）会被当作全局标志 - 子命令结构体必须实现
Execute(args []string) error方法，否则 panic -
alias:允许用app s --port=8080替代app serve --port=8080，但别和短选项冲突（如short:"s"和alias:"s"同时存在会报错） - 子命令的参数只在
Execute的args中出现，不是全局os.Args；想获取原始参数要用parser.Command().Args
自定义验证和错误处理要靠 ParseArgs + error 返回
go-flags 不提供中间件或钩子，验证逻辑必须写在 Execute 方法开头，或用 parser.ParseArgs 手动捕获错误后处理。
比如要求 --port 必须在 1024–65535 之间：
func (x *ServeOptions) Execute(args []string) error {
if x.Port 65535 {
return fmt.Errorf("--port must be between 1024 and 65535, got %d", x.Port)
}
// ... 实际逻辑
return nil
}
常见陷阱：
- 返回
nil表示成功；返回非nil error会自动打印错误并退出（除非你用parser.ParseArgs自己处理） - 不要在
Execute里调用os.Exit(1)，这会跳过go-flags的错误格式化和帮助输出 - 若需在解析阶段就校验（比如检查必填字段是否为空），应在
main中调用parser.ParseArgs(os.Args[1:])，而非parser.Parse() - 敏感参数（如
--password）不能依赖go-flags隐藏，它不处理终端掩码；应改用golang.org/x/term.ReadPassword单独读取
真正麻烦的是跨子命令共享逻辑（比如通用日志配置），go-flags 没有“父命令”概念，只能靠结构体嵌入或外部函数封装——这点容易被忽略，直到第二个子命令要复用相同校验时才暴露出来。
