Cobra 包介绍

Cobra 是一个 Golang 包,它提供了简单的接口来创建命令行程序。同时,Cobra 也是一个应用程序,用来生成应用框架,从而开发以 Cobra 为基础的应用。

img

主要功能

cobra 的主要功能如下,可以说每一项都很实用:

  • 简易的子命令行模式,如 app server, app fetch 等等
  • 完全兼容 posix 命令行模式
  • 嵌套子命令 subcommand
  • 支持全局,局部,串联 flags
  • 使用 cobra 很容易的生成应用程序和命令,使用 cobra create appname 和 cobra add cmdname
  • 如果命令输入错误,将提供智能建议,如 app srver,将提示 srver 没有,是不是 app server
  • 自动生成 commands 和 flags 的帮助信息
  • 自动生成详细的 help 信息,如 app help
  • 自动识别帮助 flag -h,–help
  • 自动生成应用程序在 bash 下命令自动完成功能
  • 自动生成应用程序的 man 手册
  • 命令行别名
  • 自定义 help 和 usage 信息
  • 可选的与 viper apps 的紧密集成

cobra 中的主要概念

cobra 中有个重要的概念,分别是 commands、arguments 和 flags。其中 commands 代表行为,arguments 就是命令行参数(或者称为位置参数),flags 代表对行为的改变(也就是我们常说的命令行选项)。执行命令行程序时的一般格式为: APPNAME COMMAND ARG –FLAG 比如下面的例子:

# server是 commands,port 是 flag
$ hugo server --port=1313

# clone 是 commands,URL 是 arguments,brae 是 flag
$ git clone URL --bare

如果是一个简单的程序(功能单一的程序),使用 commands 的方式可能会很啰嗦,但是像 git、docker 等应用,把这些本就很复杂的功能划分为子命令的形式,会方便使用(对程序的设计者来说又何尝不是如此)。

创建 cobra 应用

在创建 cobra 应用前需要先安装 cobra 包:

go get -u github.com/spf13/cobra/cobra

然后就可以用 cobra 程序生成应用程序框架了:

$ cd ~/Workspaces/cobra-demo
$ cobra init --pkg-name cobra-demo

如果不想让应用程序在默认的目录下,就要指定应用程序所在的绝对目录,比如 ~/go/src/godemos/cobrademo,生成的文件如下:

.
├── cmd
│   └── root.go
├── main.go

我们模拟docker应用,故将main.go重命名为docker.go,并尝试编译项目,此时的程序并没有什么功能,执行它只会输出一些默认的提示信息。

使用 cobra 程序生成命令代码

除了生成应用程序框架,还可以通过 cobra add 命令生成子命令的代码文件,比如下面的命令会添加两个子命令 image 和 container 相关的代码文件:

$ cd ~/Workspaces/cobra-demo
$ cobra add image

这两条命令分别生成了 docker 程序中 image 子命令的代码,当然了,具体的功能还得靠我们自己实现。

为命令添加具体的功能

到目前为止,我们一共为 docker 程序添加了两个 Command,分别是 rootCmd(cobra init 命令默认生成)和 image。 打开文件 root.go ,找到变量 rootCmd 的初始化过程并为之设置 Run 方法:

Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("docker program")
},

重新编译 docker 程序并不带参数运行,这次就不再输出帮助信息了,而是执行了 rootCmd 的 Run 方法:

$ ./docker
docker program

再创建一个 version Command 用来输出当前的软件版本。

cobra add version

这样程序就自动会在 cmd 目录下生成了 version.go 文件,编辑文件的内容如下:

var versionCmd = &cobra.Command{
	Use:   "version",
	Short: "Show the Docker version information",
	Long: `Show the Docker version information`,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println(`Client:
 Version:           18.06.0-ce
 API version:       1.38
 Go version:        go1.10.3
 Git commit:        0ffa825
 Built:             Wed Jul 18 19:05:26 2018
 OS/Arch:           darwin/amd64
 Experimental:      false

Server:
 Engine:
  Version:          18.06.0-ce
  API version:      1.38 (minimum version 1.12)
  Go version:       go1.10.3
  Git commit:       0ffa825
  Built:            Wed Jul 18 19:13:46 2018
  OS/Arch:          linux/amd64
  Experimental:     true`)
	},
}

func init() {
	rootCmd.AddCommand(versionCmd)
}

编译运行

$ ./docker version

为 Command 添加选项(flags)

选项(flags)用来控制 Command 的具体行为。根据选项的作用范围,可以把选项分为两类:

  • persistent
  • local

对于 persistent 类型的选项,既可以设置给该 Command,又可以设置给该 Command 的子 Command。对于一些全局性的选项,比较适合设置为 persistent 类型,比如控制输出的 verbose 选项:

var Verbose bool
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")

local 类型的选项只能设置给指定的 Command,比如下面定义的 source 选项:

var Source string
rootCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")

该选项不能指定给 rootCmd 之外的其它 Command。 默认情况下的选项都是可选的,但一些用例要求用户必须设置某些选项,这种情况 cobra 也是支持的,通过 Command 的 MarkFlagRequired 方法标记该选项即可:

var Name string
rootCmd.Flags().StringVarP(&Name, "name", "n", "", "user name (required)")
rootCmd.MarkFlagRequired("name")

命令行参数(arguments)

首先我们来搞清楚命令行参数(arguments)与命令行选项的区别(flags/options)。以常见的 ls 命令来说,其命令行的格式为: ls [OPTION]… [FILE]… 其中的 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 至少有一个位置参数,可以这样初始化它:

var cmdTimes = &cobra.Command{
    Use: …
    Short: …
    Long: …
    Args: cobra.MinimumNArgs(1),
    Run: …
}

帮助信息(help command)

cobra 会自动添加 –help(-h)选项,所以我们可以不必添加该选项而直接使用:

cobra 同时还自动添加了 help 子命,默认效果和使用 –help 选项相同。如果为 help 命令传递其它命令作为参数,则会显示对应命令的帮助信息,下面的命令输出 image 子命令的帮助信息:

$ cobrademo help image

当然也可以通过这种方式查看子命令的子命令的帮助文档:

$ cobrademo help image times

除了 cobra 默认的帮助命令,我们还可以通过下面的方式进行自定义:

cmd.SetHelpCommand(cmd *Command)
cmd.SetHelpFunc(f func(*Command, []string))
cmd.SetHelpTemplate(s string)

提示信息(usage message)

提示信息和帮助信息很相似,只不过它是在你输入了非法的参数、选项或命令时才出现的:

和帮助信息一样,我们也可以通过下面的方式自定义提示信息:

cmd.SetUsageFunc(f func(*Command) error)
cmd.SetUsageTemplate(s string)

在 Commnad 执行前后执行额外的操作

Command 执行的操作是通过 Command.Run 方法实现的,为了支持我们在 Run 方法执行的前后执行一些其它的操作,Command 还提供了额外的几个方法,它们的执行顺序如下: 1. PersistentPreRun 2. PreRun 3. Run 4. PostRun 5. PersistentPostRun 修改 rootCmd 的初始化代码如下:

var rootCmd = &cobra.Command{
    Use:   "cobrademo",
    Short: "sparkdev's cobra demo",
    Long: "the demo show how to use cobra package",
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PersistentPreRun with args: %v\n", args)
    },
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PreRun with args: %v\n", args)
    },
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("cobra demo program, with args: %v\n", args)
    },
    PostRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PostRun with args: %v\n", args)
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PersistentPostRun with args: %v\n", args)
    },
}

重新编译 cobrademo 程序并执行,输出结果中可以看到这些方法的执行顺序:

其中的 PersistentPreRun 方法和 PersistentPostRun 方法会伴随任何子命令的执行:

对未知命令的提示

如果我们输入了不正确的命令或者是选项,cobra 还会只能的给出提示:

上图的命令我们只输入了子命令 image 的前两个字母,但是 cobra 已经可以给出很详细的提示了。对于这样的提示我们也是可以自定义的,或者如果觉着没用就直接关闭掉。

本文 demo 的完整代码请参考。

总结

cobra 是一个非常实用(流行)的包,很多优秀的开源应用都在使用它,包括 Docker 和 Kubernetes 等等。当我们熟悉了 cobra 包的基本用法后,再去看 Docker 等应用的命令行工具的格式,是不是就很容易理解了!