Cobra眼睛蛇-强大的Golang CLI框架

阅读过k8s源码的同学，都会知道k8s Scheduler、kubeadm、kubelet等核心组件全都是通过spf13写的Cobra库来实现。本文就来详细介绍下Cobra的相关概念及具体用法。（内容译自官方文档）

关于

Cobra是一个用于Go的CLI框架。它包含一个用于创建强大的现代CLI应用程序的库和一个快速生成基于Cobra的应用程序和命令文件的工具。

它是由Go团队成员spf13为hugo创建的，已经被最流行的Go项目所采用。

Tips：知名Golang配置库viper也是该作者开发的。

Cobra提供:

• 简单的基于子命令的cli：如 app server， app fetch等等。
• 完全符合posix的flags(包括short版本和long版本)
• 嵌套的子命令
• 全局、本地和级联flags
• 使用cobra init appname和cobra add cmdname轻松生成应用程序和命令
• 智能建议(假如你将app server写成了错误的app srver)
• 自动生成命令和flags的帮助
• 自动识别help flag-h, --help等。
• 为你的应用程序自动生成bash自动完成
• 自动为应用程序生成man手册
• 命令别名，这样你就可以在不破坏它们的情况下更改内容
• 可以灵活的定义自己的帮助、用法等。
• 可选的紧密集成 viper，12-factor

安装

使用Cobra很简单。首先，使用go get安装最新版本的库。这个命令将安装cobra生成器可执行文件以及库及其依赖项:

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

接下来，在你的应用中加入Cobra:

import "github.com/spf13/cobra"

概念

Cobra是建立在commands、arguments和flags的结构上的。

Commands代表行为，Args是commands的参数，Flags 是这些行为的修饰符。

最好的应用程序在使用时读起来像一个通顺的句子。用户将知道如何使用该应用程序，因为他们会自然地理解如何使用它。

要遵循的模式是 APPNAME VERB NOUN --ADJECTIVE. 或 APPNAME COMMAND ARG --FLAG

一些真实世界的例子可以更好地说明这一点。

在下面的例子中，' server '是命令，' port '是flag:

hugo server --port=1313

在这个命令中，我们告诉Git clone bare url。

git clone URL --bare

Commands

命令是应用程序的中心点。应用程序支持的每个交互都将包含在命令中。一个命令可以有子命令并且可以选择运行一个动作。

在上面的示例中，“server”是命令。

Flags

flag是一种修改命令行为的方法。Cobra支持完全posix兼容的flag以及Go的flag包。Cobra命令可以定义持续到子命令的flag，以及仅对该命令可用的flag。

在上面的例子中，' port '是flag。

flag功能由pflag库提供，它是flag标准库的一个分支，它在添加 POSIX 合规性的同时保持相同的接口。

入门

虽然欢迎你提供自己的项目组织，但通常基于 Cobra 的应用程序将遵循以下项目结构：

  ▾ appName/
    ▾ cmd/
        add.go
        your.go
        commands.go
        here.go
      main.go

在 Cobra 应用程序中，通常 main.go 文件非常简单。它有一个目的：初始化 Cobra。

package main

import (
  "{pathToYourApp}/cmd"
)

func main() {
  cmd.Execute()
}

使用 Cobra 生成器

Cobra 提供了自己的程序，可以创建你的应用程序并添加你想要的任何命令。这是将 Cobra 合并到你的应用程序中的最简单方法。

在这里 https://github.com/spf13/cobra/blob/master/cobra/README.md 你可以找到有关它的更多信息。

使用 Cobra 库

要手动使用 Cobra，你需要创建一个干净的 main.go 文件和一个 rootCmd 文件。你可以选择提供你认为合适的其他命令。

创建 rootCmd

Cobra 不需要任何特殊的构造函数。只需创建你的命令。

理想情况下，你将它放在 app/cmd/root.go 中：

var rootCmd = &cobra.Command{
  Use:   "hugo",
  Short: "Hugo is a very fast static site generator",
  Long: `A Fast and Flexible Static Site Generator built with
                love by spf13 and friends in Go.
                Complete documentation is available at http://hugo.spf13.com`,
  Run: func(cmd *cobra.Command, args []string) {
    // Do Stuff Here
  },
}

func Execute() {
  if err := rootCmd.Execute(); err != nil {
    fmt.Println(err)
    os.Exit(1)
  }
}

你还将在 init() 函数中定义flags和handle配置。

例如cmd/root.go：

import (
  "fmt"
  "os"

  homedir "github.com/mitchellh/go-homedir"
  "github.com/spf13/cobra"
  "github.com/spf13/viper"
)

func init() {
  cobra.OnInitialize(initConfig)
  rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")
  rootCmd.PersistentFlags().StringVarP(&projectBase, "projectbase", "b", "", "base project directory eg. github.com/spf13/")
  rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "Author name for copyright attribution")
  rootCmd.PersistentFlags().StringVarP(&userLicense, "license", "l", "", "Name of license for the project (can provide `licensetext` in config)")
  rootCmd.PersistentFlags().Bool("viper", true, "Use Viper for configuration")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
  viper.BindPFlag("projectbase", rootCmd.PersistentFlags().Lookup("projectbase"))
  viper.BindPFlag("useViper", rootCmd.PersistentFlags().Lookup("viper"))
  viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
  viper.SetDefault("license", "apache")
}

func initConfig() {
  // Don't forget to read config either from cfgFile or from home directory!
  if cfgFile != "" {
    // Use config file from the flag.
    viper.SetConfigFile(cfgFile)
  } else {
    // Find home directory.
    home, err := homedir.Dir()
    if err != nil {
      fmt.Println(err)
      os.Exit(1)
    }

    // Search config in home directory with name ".cobra" (without extension).
    viper.AddConfigPath(home)
    viper.SetConfigName(".cobra")
  }

  if err := viper.ReadInConfig(); err != nil {
    fmt.Println("Can't read config:", err)
    os.Exit(1)
  }
}

创建你的 main.go

使用 root 命令，你需要让主函数执行它。为清楚起见，应在根目录上运行 Execute，尽管它可以在任何命令上调用。

在 Cobra 应用程序中，通常 main.go 文件非常简单。它的一个目的是初始化 Cobra。

package main

import (
  "{pathToYourApp}/cmd"
)

func main() {
  cmd.Execute()
}

创建附加命令

可以定义其他命令，通常每个命令在 cmd/ 目录中都有自己的文件。

如果你想创建一个版本命令，你可以创建 cmd/version.go 并用以下内容填充它：

package cmd

import (
  "fmt"

  "github.com/spf13/cobra"
)

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

var versionCmd = &cobra.Command{
  Use:   "version",
  Short: "Print the version number of Hugo",
  Long:  `All software has versions. This is Hugo's`,
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
  },
}

使用Flags

Flags提供修饰符来控制操作命令的操作方式。

为命令分配Flags

由于Flags是在不同的位置定义和使用的，因此我们需要在外部定义一个具有正确范围的变量来分配要使用的Flags。

var Verbose bool
var Source string

有两种不同的方法来分配标志。

持久flag

flag可以是“持久的”，这意味着该flag将可用于分配给它的命令以及该命令下的每个命令。对于全局flag，将flag分配为根上的持久flag。

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

本地flag

也可以在本地分配一个flag，它只适用于该特定命令。

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

父命令的本地flag

默认情况下，Cobra 仅解析目标命令上的本地flag，忽略父命令上的任何本地flag。通过启用Command.TraverseChildrenCobra 将在执行目标命令之前解析每个命令的本地flag。

command := cobra.Command{
  Use: "print [OPTIONS] [COMMANDS]",
  TraverseChildren: true,
}

使用配置绑定标志

你也可以用viper https://github.com/spf13/viper 绑定你的标志：

var author string

func init() {
  rootCmd.PersistentFlags().StringVar(&author, "author", "YOUR NAME", "Author name for copyright attribution")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
}

在此示例中，持久flag author与 绑定viper。 请注意，当用户未提供标志时，变量author将不会设置为配置中的值。--author

在本例中，持久标志author与viper绑定。注意，当user没有提供--author flag时，变量author不会被设置为config中的值。

更多信息请参见viper 文档。

必需的flag

默认情况下，flag是可选的。相反，如果你希望你的命令在未设置flag时报告错误，请将其标记为必需：

rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkFlagRequired("region")

位置和自定义参数

位置参数的验证可以使用Command的Args字段指定。

内置了以下验证器：

• NoArgs - 如果有任何位置参数，该命令将报告错误。
• ArbitraryArgs - 该命令将接受任何参数。
• OnlyValidArgs - 如果有任何位置参数不在 的ValidArgs字段中，该命令将报告错误Command。
• MinimumNArgs(int) - 如果没有至少 N 个位置参数，该命令将报告错误。
• MaximumNArgs(int) - 如果有超过 N 个位置参数，该命令将报告错误。
• ExactArgs(int) - 如果不完全有 N 个位置参数，该命令将报告错误。
• ExactValidArgs(int) = 如果不完全有 N 个位置参数，或者如果有任何位置参数ValidArgs不在Command
• RangeArgs(min, max) - 如果 args 的数量不在预期 args 的最小和最大数量之间，该命令将报告错误。

设置自定义验证器的示例：

var cmd = &cobra.Command{
  Short: "hello",
  Args: func(cmd *cobra.Command, args []string) error {
    if len(args) < 1 {
      return errors.New("requires at least one arg")
    }
    if myapp.IsValidColor(args[0]) {
      return nil
    }
    return fmt.Errorf("invalid color specified: %s", args[0])
  },
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hello, World!")
  },
}

例子

在下面的示例中，我们定义了三个命令。两个在顶层，一个 (cmdTimes) 是顶级命令之一的子级。在这种情况下，root 是不可执行的，这意味着需要一个子命令。这是通过不为“rootCmd”提供“运行”来实现的。

我们只为单个命令定义了一个flag。

有关flag的更多文档，请访问https://github.com/spf13/pflag

package main

import (
  "fmt"
  "strings"

  "github.com/spf13/cobra"
)

func main() {
  var echoTimes int

  var cmdPrint = &cobra.Command{
    Use:   "print [string to print]",
    Short: "Print anything to the screen",
    Long: `print is for printing anything back to the screen.
For many years people have printed back to the screen.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Print: " + strings.Join(args, " "))
    },
  }

  var cmdEcho = &cobra.Command{
    Use:   "echo [string to echo]",
    Short: "Echo anything to the screen",
    Long: `echo is for echoing anything back.
Echo works a lot like print, except it has a child command.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Print: " + strings.Join(args, " "))
    },
  }

  var cmdTimes = &cobra.Command{
    Use:   "times [# times] [string to echo]",
    Short: "Echo anything to the screen more times",
    Long: `echo things multiple times back to the user by providing
a count and a string.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      for i := 0; i < echoTimes; i++ {
        fmt.Println("Echo: " + strings.Join(args, " "))
      }
    },
  }

  cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")

  var rootCmd = &cobra.Command{Use: "app"}
  rootCmd.AddCommand(cmdPrint, cmdEcho)
  cmdEcho.AddCommand(cmdTimes)
  rootCmd.Execute()
}

更加完整示例，请查看Hugo。

帮助命令

当你有子命令时，Cobra 会自动向你的应用程序添加帮助命令。这将在用户运行“应用程序帮助”时调用。此外，帮助还将支持所有其他命令作为输入。比如说，你有一个名为“create”的命令，没有任何额外的配置；Cobra 将在调用“app help create”时工作。每个命令都会自动添加“–help”标志。

例子

以下输出由 Cobra 自动生成。除了命令和标志定义之外，什么都不需要。

$ cobra help

Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.

Usage:
  cobra [command]

Available Commands:
  add         Add a command to a Cobra Application
  help        Help about any command
  init        Initialize a Cobra Application

Flags:
  -a, --author string    author name for copyright attribution (default "YOUR NAME")
      --config string    config file (default is $HOME/.cobra.yaml)
  -h, --help             help for cobra
  -l, --license string   name of license for the project
      --viper            use Viper for configuration (default true)

Use "cobra [command] --help" for more information about a command.

帮助就像任何其他命令一样只是一个命令。它没有特殊的逻辑或行为。事实上，如果需要，你可以提供自己的。

定义你自己的help

你可以为默认命令提供自己的帮助命令或你自己的模板，以与以下功能一起使用：

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

后两者也适用于任何子命令。

用法信息

当用户提供无效标志或无效命令时，Cobra 通过向用户显示“usage”来响应。

Example

你可能会从上面的帮助中认识到这一点。这是因为默认帮助将用法作为其输出的一部分嵌入。

$ cobra --invalid
Error: unknown flag: --invalid
Usage:
  cobra [command]

Available Commands:
  add         Add a command to a Cobra Application
  help        Help about any command
  init        Initialize a Cobra Application

Flags:
  -a, --author string    author name for copyright attribution (default "YOUR NAME")
      --config string    config file (default is $HOME/.cobra.yaml)
  -h, --help             help for cobra
  -l, --license string   name of license for the project
      --viper            use Viper for configuration (default true)

Use "cobra [command] --help" for more information about a command.

定义自己的 usage

你可以提供自己的使用函数或模板供 Cobra 使用。像帮助一样，函数和模板可以通过公共方法覆盖：

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

Version Flag

如果在根命令上设置了 Version 字段，Cobra 会添加一个顶级“--version”标志。使用“--version”标志运行应用程序将使用版本模板将版本打印到标准输出。可以使用cmd.SetVersionTemplate(s string)函数自定义模板。

PreRun 和 PostRun 钩子

可以在命令的main Run函数之前或之后运行函数。PersistentPreRun和PreRun函数将在Run之前执行。PersistentPostRun和PostRun将在Run之后执行。如果Persistent*Run函数没有声明自己的，则将由子函数继承。这些函数的运行顺序如下:

• PersistentPreRun
• PreRun
• Run
• PostRun
• PersistentPostRun

下面是使用所有这些特性的两个命令的示例。当子命令被执行时，它将运行根命令的PersistentPreRun，而不是根命令的PersistentPostRun:

package main

import (
  "fmt"

  "github.com/spf13/cobra"
)

func main() {

  var rootCmd = &cobra.Command{
    Use:   "root [sub]",
    Short: "My root command",
    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("Inside rootCmd Run 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)
    },
  }

  var subCmd = &cobra.Command{
    Use:   "sub [no options!]",
    Short: "My subcommand",
    PreRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd PreRun with args: %v\n", args)
    },
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd Run with args: %v\n", args)
    },
    PostRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd PostRun with args: %v\n", args)
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
      fmt.Printf("Inside subCmd PersistentPostRun with args: %v\n", args)
    },
  }

  rootCmd.AddCommand(subCmd)

  rootCmd.SetArgs([]string{""})
  rootCmd.Execute()
  fmt.Println()
  rootCmd.SetArgs([]string{"sub", "arg1", "arg2"})
  rootCmd.Execute()
}

输出

Inside rootCmd PersistentPreRun with args: []
Inside rootCmd PreRun with args: []
Inside rootCmd Run with args: []
Inside rootCmd PostRun with args: []
Inside rootCmd PersistentPostRun with args: []

Inside rootCmd PersistentPreRun with args: [arg1 arg2]
Inside subCmd PreRun with args: [arg1 arg2]
Inside subCmd Run with args: [arg1 arg2]
Inside subCmd PostRun with args: [arg1 arg2]
Inside subCmd PersistentPostRun with args: [arg1 arg2]

发生“unknown command”时的建议

当“unknown command”错误发生时，Cobra将自动打印建议。这使得Cobra在发生错字时的行为与git命令类似。例如:

$ hugo srever
Error: unknown command "srever" for "hugo"

Did you mean this?
        server

Run 'hugo --help' for usage.

建议基于注册的每个子命令，并使用Levenshtein distance的实现。每个匹配最小距离为2(忽略大小写)的已注册命令都将显示为建议。

如果你需要禁用建议或调整命令中的字符串距离，请使用:

command.DisableSuggestions = true

或

command.SuggestionsMinimumDistance = 1

你还可以使用SuggestFor属性显式地设置指定命令的建议名称。这允许对字符串距离不近，但在你的命令集中有意义的字符串以及一些你不需要别名的字符串提供建议。

例子:

$ kubectl remove
Error: unknown command "remove" for "kubectl"

Did you mean this?
        delete

Run 'kubectl help' for usage.

为你的命令生成文档

Cobra 可以基于以下格式的子命令、标志等生成文档：

• Markdown
• ReStructured Text
• Man Page

生成bash补全

Cobra可以生成一个bash完成文件。如果在命令中添加更多信息，这些补全功能就会非常强大和灵活。你可以在Bash补全中阅读更多信息。

官网链接：https://cobra.dev/