CLI开发工具【免费下载链接】cliA declarative, simple, fast, and fun package for building command line tools in Go项目地址https://gitcode.com/gh_mirrors/cli1/cli点击查看免费下载导读旗标Flag即命令行选项是 Go CLI 工具与用户交互的核心接口。本文以 docs/v2/examples/flags.md 为骨架系统讲解 urfave/cli v2 中旗标的定义与查询、目标变量绑定、布尔计数、别名、多值、排序、环境变量/文件/外部输入源取值、必填约束、默认值展示与自定义 Action 校验并结合本仓库源码揭示其底层实现。读完本文你将能写出声明式、可维护且具备完整取值链路的命令行工具。说明本文示例基于 v2 API导入github.com/urfave/cli/v2源码佐证部分参考当前仓库 v3 实现见 go.mod两者在本文所讲的核心概念上保持一致差异处会单独标注。定义与查询 Flag从一个问候程序说起在 urfave/cli 中Flag 通过app.Flags字段声明每个旗标是一个实现了cli.Flag接口的结构体实例。最基本的用法是声明一个带默认值的字符串旗标并在 Action 中通过cCtx.String(lang)查询package main import ( fmt log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Value: english, Usage: language for the greeting, }, }, Action: func(cCtx *cli.Context) error { name : Nefertiti if cCtx.NArg() 0 { name cCtx.Args().Get(0) } if cCtx.String(lang) spanish { fmt.Println(Hola, name) } else { fmt.Println(Hello, name) } return nil }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }运行时不带--lang参数Value指定的english即生效输出Hello Nefertiti带上--lang spanish则输出Hola Nefertiti。Value字段的意义就是命令行未指定时的默认值。注意从源码结构看v3 中所有基础旗标都收敛为泛型基类FlagBase[T, C, VC]例如 flag_string.go 中type StringFlag FlagBase[string, StringConfig, stringValue]Value、Destination、Aliases、Action、Required等字段统一定义在 flag_impl.go 的结构体中因此下文讲到的各类字段对所有旗标类型通用。绑定目标变量Destination 自动填充除了在 Action 里用cCtx.String(...)查询你还可以为旗标指定一个Destination指针解析完成后值会被自动扫描进该变量后续直接读取变量即可package main import ( fmt log os github.com/urfave/cli/v2 ) func main() { var language string app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Value: english, Usage: language for the greeting, Destination: language, }, }, Action: func(cCtx *cli.Context) error { name : someone if cCtx.NArg() 0 { name cCtx.Args().Get(0) } if language spanish { fmt.Println(Hola, name) } else { fmt.Println(Hello, name) } return nil }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }关键语义有两点其一如果同时设置了Value该默认值会在命令行解析前先写入Destination其二Destination的声明方式需要与旗标类型一致——StringFlag对应*string、IntFlag对应*int。在 v3 的FlagBase中Destination *T直接以泛型类型参数约束见 flag_impl.go从根本上避免了类型不匹配的隐患。布尔旗标计数-vvv与 Count布尔旗标可以重复出现来计数如-v -v -v或-vvv通过BoolFlag的Count指针接收次数。但要支持-vvv这种合并短选项写法必须先开启App.UseShortOptionHandlingpackage main import ( fmt log os github.com/urfave/cli/v2 ) func main() { var count int app : cli.App{ UseShortOptionHandling: true, Flags: []cli.Flag{ cli.BoolFlag{ Name: foo, Usage: foo greeting, Aliases: []string{f}, Count: count, }, }, Action: func(cCtx *cli.Context) error { fmt.Println(count, count) return nil }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }当命令行传入--foo --foo -fff -f时程序输出count 6-fff在UseShortOptionHandling开启时被拆解为三次-f。从源码看UseShortOptionHandling是 command.go 中Command的一个布尔字段而 v3 的BoolFlag通过 flag_bool.go 中的Count *int指针实现且当Count为 nil 时会在内部new(int)初始化见 flag_bool.go所以该字段可以放心省略初始化。占位符值在 Usage 中标注参数名有时希望在帮助文本里展示旗标接受的参数名如--config FILE只需在Usage字符串中用反引号包裹占位词package main import ( log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: config, Aliases: []string{c}, Usage: Load configuration from FILE, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }--help的输出会变成--config FILE, -c FILE Load configuration from FILE注意只有第一个反引号包裹的词会被提取为占位符后续的反引号词将原样保留。别名为旗标提供短名称通过Aliases字段可以为旗标指定一个或多个别名package main import ( log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Aliases: []string{l}, Value: english, Usage: language for the greeting, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }该旗标既可以用--lang spanish也可以用-l spanish设置。但要注意同一次命令调用中如果同一旗标以两种不同形式各出现一次如既写--lang又写-l会被视为错误。从实现上看v2 中Aliases与Name共同组成旗标的全部可用名称v3 对应 flag_impl.go 的Names()方法合并Name与Aliases。单旗标多值Slice 旗标当需要为一个旗标传入多个值时使用切片类旗标解析结果以切片形式提供。v2 中可用的切片旗标有Int64SliceFlagIntSliceFlagStringSliceFlagpackage main import ( fmt log os strings github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringSliceFlag{ Name: greeting, Usage: Pass multiple greetings, }, }, Action: func(cCtx *cli.Context) error { fmt.Println(strings.Join(cCtx.StringSlice(greeting), , )) return nil }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }多个值必须以重复旗标的方式传递例如--greeting Hello --greeting Hola程序输出Hello, Hola。需要说明的是上述示例中的StringSliceFlag写法同样适用于 v3v3 中切片旗标默认还支持逗号分隔相关解析配置见 flag_impl.go 的SliceFlagSeparator默认,。另外除切片旗标外大多数旗标重复出现时只有最后一次的值生效。排序FlagsByName 与 CommandsByName应用与命令的旗标默认按声明顺序展示在帮助中。若想按字母序排列可以在Run之前用sort包对app.Flags和app.Commands排序package main import ( log os sort github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Aliases: []string{l}, Value: english, Usage: Language for the greeting, }, cli.StringFlag{ Name: config, Aliases: []string{c}, Usage: Load configuration from FILE, }, }, Commands: []*cli.Command{ { Name: complete, Aliases: []string{c}, Usage: complete a task on the list, Action: func(*cli.Context) error { return nil }, }, { Name: add, Aliases: []string{a}, Usage: add a task to the list, Action: func(*cli.Context) error { return nil }, }, }, } sort.Sort(cli.FlagsByName(app.Flags)) sort.Sort(cli.CommandsByName(app.Commands)) if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }排序后的帮助输出变为--config FILE, -c FILE Load configuration from FILE --lang value, -l value Language for the greeting (default: english)从源码看cli.FlagsByName定义于 flag.go其Less方法调用 sort.go 中的lexicographicLess进行忽略大小写、再比较原始字符的字典序比较CommandsByName同理二者都实现了sort.Interface可直接配合标准库sort.Sort使用。从环境变量取值EnvVars可以让旗标默认值来自环境变量package main import ( log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Aliases: []string{l}, Value: english, Usage: language for the greeting, EnvVars: []string{APP_LANG}, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }帮助输出中会自动标注来源环境变量language for the greeting (default: english) (env: APP_LANG)。当EnvVars包含多个变量名时第一个解析成功的环境变量生效app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Aliases: []string{l}, Value: english, Usage: language for the greeting, EnvVars: []string{LEGACY_COMPAT_LANG, APP_LANG, LANG}, }, }, }这为旧配置优先兼容、新配置兜底的迁移场景提供了便利。v3 中环境变量属于ValueSourceChain的一部分GetEnvVars()即返回f.Sources.EnvKeys()见 flag_impl.go。从文件取值FilePathFilePath字段可让旗标默认值来自文件内容package main import ( log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: password, Aliases: []string{p}, Usage: password for the mysql database, FilePath: /etc/mysql/password, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }优先级注意FilePath提供的默认值优先级高于EnvVar提供的默认值环境变量仅在文件未命中时作为兜底。从其他输入源取值YAML / JSON / TOMLaltsrc除了环境变量与文件urfcave/cli 还通过独立的altsrc包支持从 YAML、JSON、TOML 等结构化文件读取旗标值。v2 中该包位于github.com/urfave/cli/v2/altsrc从本仓库 README.md 与 docs/go.mod 可见v3 已将其拆分维护为urfave/cli-altsrc独立模块概念与用法保持一致。使用方式是把现有旗标用 altsrc 包装并初始化输入源// 包装现有旗标使它能从外部输入源取值 altsrc.NewIntFlag(cli.IntFlag{Name: test})// 在命令执行前根据 --load 旗标指定的文件名初始化 YAML 输入源 command.Before altsrc.InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc(load))上述代码会用load作为旗标名从cli.Context中取得 YAML 文件名再以该文件初始化此命令上所有被 altsrc 包装旗标的输入源。因此load旗标本身也必须定义在命令的Flags中否则代码无法工作。完整的命令级示例package main import ( fmt os github.com/urfave/cli/v2 github.com/urfave/cli/v2/altsrc ) func main() { flags : []cli.Flag{ altsrc.NewIntFlag(cli.IntFlag{Name: test}), cli.StringFlag{Name: load}, } app : cli.App{ Action: func(*cli.Context) error { fmt.Println(--test value.*default: 0) return nil }, Before: altsrc.InitInputSourceWithContext(flags, altsrc.NewYamlSourceFromFlagFunc(load)), Flags: flags, } app.Run(os.Args) }目前官方支持 YAML、JSON、TOML 三种格式如需其他格式开发者可以实现altsrc.InputSourceContext接口来接入自定义输入源。必填旗标Required将Required字段置为true即可强制用户提供该旗标package main import ( fmt log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.StringFlag{ Name: lang, Value: english, Usage: language for the greeting, Required: true, }, }, Action: func(cCtx *cli.Context) error { output : Hello if cCtx.String(lang) spanish { output Hola } fmt.Println(output) return nil }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }未提供lang旗标时程序直接报错退出并显示Required flag lang not set在 v3 实现中Required是FlagBase的公开字段并有配套的IsRequired()方法见 flag_impl.go供校验逻辑统一查询。为帮助输出定制默认值文本DefaultText当默认值是运行时计算出来的例如随机端口直接把计算逻辑塞进Value会让帮助文本难以理解。此时可用DefaultText覆盖帮助中的默认值展示package main import ( log os github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.IntFlag{ Name: port, Usage: Use a randomized port, Value: 0, DefaultText: random, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }帮助输出为--port value Use a randomized port (default: random)v3 中DefaultText string同样是FlagBase字段flag_impl.go并可由GetDefaultText()读取flag_impl.go。值来源优先级当一个旗标同时有命令行、环境变量、配置文件与默认值多条取值路径时按以下优先级从高到低解析命令行传入的旗标值环境变量若指定配置文件若指定如 altsrc / FilePath旗标上定义的默认值理解这条优先级链是排查为什么我的配置没生效的关键——命令行永远最高默认值永远兜底。Flag Action按旗标注册处理函数每个旗标都可以注册一个Action回调在该旗标被解析处理后触发最常见的用途是旗标值校验package main import ( log os fmt github.com/urfave/cli/v2 ) func main() { app : cli.App{ Flags: []cli.Flag{ cli.IntFlag{ Name: port, Usage: Use a randomized port, Value: 0, DefaultText: random, Action: func(ctx *cli.Context, v int) error { if v 65536 { return fmt.Errorf(Flag port value %v out of range[0-65535], v) } return nil }, }, }, } if err : app.Run(os.Args); err ! nil { log.Fatal(err) } }当运行--port 70000时Action 返回错误程序输出并退出Flag port value 70000 out of range[0-65535]从 v3 源码看旗标 Action 统一为func(context.Context, *Command, T) error签名flag_impl.go由RunAction方法在旗标解析后调用返回值直接并入命令执行链的错误处理flag_impl.go。结语与进一步阅读至此你已掌握 urfave/cli v2 旗标体系的全部核心能力从最基础的StringFlag声明与cCtx.String()查询到Destination绑定、-vvv计数、别名与占位符、切片多值、FlagsByName排序再到环境变量、文件与 YAML/JSON/TOML 等多级取值源、Required必填约束、DefaultText展示定制与 Action 校验以及贯穿始终的值来源优先级。同类主题的更多资料可在仓库内继续查阅本仓库对应 v3 的旗标进阶用法docs/v3/examples/flags/advanced.md、docs/v3/examples/flags/short-options.md、docs/v3/examples/flags/value-sources.md完整 API 参考godoc-current.txt旗标相关源码与测试flag.go、flag_impl.go、flag_test.go、sort.go组合短选项与退出码docs/v2/examples/combining-short-options.md、docs/v2/examples/exit-codes.md赞分享CLI开发工具【免费下载链接】cliA declarative, simple, fast, and fun package for building command line tools in Go项目地址https://gitcode.com/gh_mirrors/cli1/cli点击查看免费下载相关推荐urfave/cli v3 标志Flag入门指南定义、解析、读取与版本标志定制urfave/cli v3 标志Flag入门指南定义、解析、读取与版本标志定制 本指南以 urfave/cli v3 的 flags/basics.mdCLI开发工具urfave/cli v2 版本标志完全指南自定义 -v/--version 与重写 cli.VersionPrinterurfave/cli v2 版本标志完全指南自定义 v/ version 与重写 cli.VersionPrinter 导读 本文以 urfave/cli vCLI开发工具10个Buckwheat使用技巧从新手到理财达人的快速进阶指南10个Buckwheat使用技巧从新手到理财达人的快速进阶指南 Buckwheat是一款专为Android用户设计的理财应用采用Jetpack Compos上一篇旧 Mac 免费装回最新 macOSOpenCore Legacy Patcher 从零到上手的完整指南下一篇ipympl高级技巧自定义交互行为与事件处理详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考