Cobra
Cobra是一个为创建命令行程序提供了强大接口的Go Library,同时也是一个用来生成应用框架的应用程序。在Go的世界中,很多 知名项目 比如Docker、Kubernetes、Hugo等都使用了Cobra。本文将介绍Cobra包的基本使用,并介绍其实现原理,本文中使用的代码可以参考我的 github。
Cobra包提供了以下特性:
- 简易的子命令行模式,如 app server, app fetch 等等
- 完全兼容 posix 命令行模式,包括short&long versions
- 嵌套子命令 subcommand
- 支持全局,局部,级联 flags
- 使用 cobra 很容易的生成应用程序和命令,使用
cobra init appname和cobra add cmdname - 如果命令输入错误,将提供智能建议,如
app srver,将提示did you mean app server - 自动生成 commands 和 flags 的帮助信息
- 自动生成详细的 help 信息,如 app help
- 自动识别帮助 flag -h,–help
- 自动生成应用程序在 bash 下命令自动完成功能
- 自动生成应用程序的 man 手册
- 命令行别名
- 自定义 help 和 usage 信息
- 可选的与 viper apps 的紧密集成
Concepts
cobra 中有个重要的概念,分别是 commands、arguments 和 flags。其中 commands 代表行为,arguments 就是命令行参数(或者称为位置参数),flags 代表对行为的改变(也就是我们常说的命令行选项)。执行命令行程序时的一般格式为:
APPNAME COMMAND ARG --FLAG
比如下面的例子:
|
|
如果是一个简单的程序(功能单一的程序),使用 commands 的方式可能会很啰嗦,但是像 git、docker 等应用,把这些本就很复杂的功能划分为子命令的形式,会方便使用(对程序的设计者来说又何尝不是如此)。
Cobra支持像 Go flag 一样的兼容POSIX的命令行参数,通过 pflag library 支持。
Getting Started
创建 cobra 应用
在创建 cobra 应用前需要先安装 cobra 包:
|
|
然后就可以使用 cobra 生成应用程序框架
|
|
生成目录如下:
|
|
查看生成代码:
|
|
可以看到 main.go 非常简单,主要代码逻辑在 cmd/root.go 中
|
|
编译程序并运行,可以看到:
|
|
下面依次分析创建命令的每个部分。
创建 rootCmd
Cobra 不需要额外的创建特殊的构造函数,只需要简单的创建你自己的命令。
|
|
你可以在 init 函数中定义命令行参数并处理配置文件:
|
|
自动生成子命令
除了生成应用程序框架,还可以通过 cobra add 命令生成子命令的代码文件,比如下面的命令会添加子命令 image 和 相关的代码文件:
|
|
创建自定义命令
打开文件 root.go ,找到变量 rootCmd 的初始化过程并为之设置 Run 方法:
|
|
编译之后并不带参数运行,这次就不再输出帮助信息了,而是执行了 rootCmd 的 Run 方法:
|
|
再创建一个 version Command 用来输出当前的软件版本。先在 cmd 目录下添加 version.go 文件,编辑文件的内容如下:
|
|
编译程序运行命令如下:
|
|
如果你想要获得执行命令返回的错误,可以使用 RunE 函数:
|
|
创建命令行 Flags
选项(flags)用来控制 Command 的具体行为。根据选项的作用范围,可以把选项分为两类:
- persistent
- local
对于 persistent 类型的选项,既可以设置给该 Command,又可以设置给该 Command 的子 Command。对于一些全局性的选项,比较适合设置为 persistent 类型,比如控制输出的 verbose 选项:
|
|
local 类型的选项只能设置给指定的 Command,比如下面定义的 source 选项:
|
|
该选项不能指定给 rootCmd 之外的其它 Command。
默认情况下的选项都是可选的,但一些用例要求用户必须设置某些选项,这种情况 cobra 也是支持的,通过 Command 的 MarkFlagRequired 方法标记该选项即可:
|
|
创建命令行参数
首先我们来搞清楚命令行参数(arguments)与命令行选项的区别(flags/options)。以常见的 ls 命令来说,其命令行的格式为:
|
|
其中的 OPTION 对应本文中介绍的 flags,以 - 或 – 开头;而 FILE 则被称为参数(arguments)或位置参数。一般的规则是参数在所有选项的后面,上面的 … 表示可以指定多个选项和多个参数。
cobra 默认提供了一些验证方法:
- NoArgs - 如果存在任何位置参数,该命令将报错
- ArbitraryArgs - 该命令会接受任何位置参数
- OnlyValidArgs - 如果有任何位置参数不在命令的 ValidArgs 字段中,该命令将报错
- MinimumNArgs(int) - 至少要有 N 个位置参数,否则报错
- MaximumNArgs(int) - 如果位置参数超过 N 个将报错
- ExactArgs(int) - 必须有 N 个位置参数,否则报错
- ExactValidArgs(int) 必须有 N 个位置参数,且都在命令的 ValidArgs 字段中,否则报错
- RangeArgs(min, max) - 如果位置参数的个数不在区间 min 和 max 之中,报错
比如要让 Command cmdTimes 至少有一个位置参数,可以这样初始化它:
|
|
我们在前面创建的代码的基础上,为 image 命令添加行为(打印信息到控制台),并为它添加一个子命令 cmdTimes,下面是更新后的 image.go 文件的内容:
|
|
执行命令:
|
|
帮助信息 help command
cobra 会自动添加 –help(-h)选项,所以我们可以不必添加该选项而直接使用:
|
|
参考资料
-
No backlinks found.