CLI应用程序的库Cobra

发布时间：2020-07-14 13:39:40 作者：recallsong
来源：网络阅读：4523

Cobra既是用于创建强大的现代CLI应用程序的库，也是用于生成应用程序和命令文件的程序。
许多使用最广泛的Go项目都是使用Cobra构建的，其中包括：

Kubernetes
Hugo
rkt
etcd
Moby (former Docker)
Docker (distribution)
OpenShift
Delve
GopherJS
CockroachDB
Bleve
ProjectAtomic (enterprise)
GiantSwarm's swarm
Nanobox/Nanopack
rclone
nehm
Pouch

概述

Cobra是一个库，提供了一个简单的接口来创建功能强大的类似于git和go的现代CLI程序。
Cobra也是一个应用程序，帮助你生成应用程序脚手架，以快速开发基于Cobra的应用程序。
Cobra提供了：

简单的基于子命令的CLI：app server, app fetch 等。
完全兼容POSIX命令行参数flag（包括长版本和短版本）
嵌套子命令
全局，局部和及联的flags
使用cobra init appname＆cobra add cmdname命令很容易生成应用程序
智能提示（app srver... did you mean app server?）
为命令和flag自动生成帮助
自动识别-h,--help标志来显示帮助信息等
为您的应用程序自动生成bash autocomplete
为您的应用程序自动生成手册页
命令别名功能
自定义您的帮助信息，使用信息等
可选的，集成viper来写12-factor的应用

概念

CobraCobra建立在命令，参数和标志的结构上。
命令表示动作，参数是事物，标志是这些动作的修饰符。
最好的应用程序的命令使用起来应该像一个句子一样。用户将知道如何使用应用程序，因为很自然就明白意思。
遵循的模式是APPNAME VERB NOUN --ADJECTIVE. 或 APPNAME COMMAND ARG --FLAG
举几个现实中比较好的例子来说明这一点。
在下面的例子中，server是一个命令，port是一个标志：

hugo server --port=1313

下面这个命令告诉我们git以bare方式克隆URL

git clone URL --bare

命令

命令是应用程序的中心，应用程序所支持的每一个交互都包含在命令中，一个命令可以有子命令，并可以选择运行一个动作。
在上面的例子中，server是一个命令
关于cobra.Command文档

Flag

标志是修改命令行为的一种方式。Cobra完全符合POSIX的标志和Go的标志。Cobra命令可以定义所有命令都能使用的persist标志，也能定义仅对某命令有效的标志。
在上面的例子中，port是标志。
标志功能由pflag库提供，这是标准库中flag的一个分支，它在保持相同接口的同时增加了POSIX合规性。

安装

使用Cobra很容易。首先，使用go get安装最新版本的库。该命令将安装可执行的cobra生成器，库和它的依赖库：

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

接下来，在你的应用程序中国年包含Cobra：

import "github.com/spf13/cobra"

入门

尽管欢迎您提供自己的组织，但通常基于Cobra的应用程序将遵循以下组织结构：

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

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

package main

import (
  "fmt"
  "os"

  "{pathToYourApp}/cmd"
)

func main() {
  cmd.Execute()
}

使用Cobra生成器

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

Cobra初始

cobra init [app] 命令将为你创建初始的应用程序代码。这是一个功能非常强大的应用程序，它可以使您的程序具有适当的结构，因此您可以立即享受到Cobra的所有好处。它也会自动将您指定的许可证应用于你的应用程序。
Cobra init非常聪明。您可以提供完整的路径，或者只是一个类似于导入路径：

cobra init github.com/spf13/newApp

Cobra添加

应用程序初始化后，Cobra可以为您创建其他命令。假设您创建了一个应用程序，并且需要以下命令：

app serve
app config

app config create
在您的项目目录中（您的main.go文件所在的位置），您可以运行以下命令：

cobra add serve
cobra add config
cobra add create -p 'configCmd'

注意：对于命令名称使用camelCase（不是snake_case / snake-case）。否则，你会遇到错误。例如，cobra add add-user不正确，但是cobra add addUser有效。
一旦你运行了这三个命令，你就会有一个类似于以下的应用程序结构：

▾ app/
▾ cmd/
    serve.go
    config.go
    create.go
  main.go

此时你可以运行go run main.go，它会运行你的应用程序。go run main.go serve，go run main.go config，go run main.go config create以及go run main.go help serve等都可以执行。
显然你还没有添加你自己的代码。但这些命令已准备好了。

配置Cobra

如果您提供一个简单的配置文件，Cobra生成器将更易于使用，这将帮助您避免在标志中反复提供大量重复信息。
例如~/.cobra.yaml文件：

author: Steve Francia <spf@spf13.com>
license: MIT

您可以通过设置license为指定任何许可证，none或者您也可以指定自定义许可证：

license:
header: This file is part of {{ .appName }}.
text: |
{{ .copyright }}

This is my license. There are many like it, but this one is mine.
My license is my best friend. It is my life. I must master it as I must
master my life.

您也可以使用内置许可证。例如，GPLv2，GPLv3，LGPL， AGPL，MIT，2-Clause BSD或3-Clause BSD。

使用Cobra库

要手动实现Cobra您需要提供一个简洁的mai.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函数中定义标志并处理配置：
例如 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，但为了清晰起见，应该在根上运行Execute。

在Cobra应用程序中，通常main.go文件非常简洁。它用于初始化Cobra。

package main

import (
  "fmt"
  "os"

  "{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")
        },
    }

使用标志

标志是用来控制命令行为的一种方式。

将标志分配给命令

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

var Verbose bool
var Source string

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

持久标志

一个标志是可以持久的，着意味着这个标志将可以用于它分配的命令以及该命令下的每个命令。对于全局标志，在根上分配一个标志作为持久标志。

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

本地标志

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

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

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

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

使用Config绑定标志

你可以绑定你的flag到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"))
}

在这个例子中，持久标志author被绑定到了viper。请注意，如果用户没有从viper中提供值，则该author不会被设置。
了解更多请看viper文档

必需的标志

标志默认是可选的，如果你希望在没有提供标志时报错，请将标志标记为必需的：

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

位置和自定义参数

位置参数的校验可以使用Command的Args字段。
以下是内置的校验器：

NoArgs - 如果有任何参数，该命令将报告错误。
ArbitraryArgs - 该命令将接受任何参数。
OnlyValidArgs- 如果有任何不在ValidArgs字段中的参数，则该命令将报告错误。
MinimumNArgs(int) - 如果没有至少N个位置参数，该命令将报告错误。
MaximumNArgs(int) - 如果存在多于N个位置参数，则该命令将报告错误。
ExactArgs(int) - 如果不存在完全N个位置参数，则该命令将报告错误。

RangeArgs(min, max) - 如果参数的数量这个某个范围之间，则该命令将报告错误。
设置自定义校验器的示例：

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就是顶层命令的子命令之一。在这种情况下，根不可执行，这意味着需要子命令。这是通过不为'rootCmd'提供'Run'来实现的。

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

有关标志的更多文档可在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会自动为您的应用程序添加一条帮助命令。用户运行“app help”命令时调用该帮助命令。此外，帮助还将支持所有其他的命令作为输入。比如说，你有一个叫做'create'的命令，没有任何额外的配置; 帮助命令将在'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.

帮助就像任何其他命令一样。周围没有特殊的逻辑或行为。事实上，如果你愿意，你可以提供你自己的。

自定义帮助命令

你可以提供自己的帮助命令或自己的模版，用一下函数：

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

后面两个函数也应用于任何子命令。

使用信息

当用户提供无效的标志或无效的命令时，Cobra会显示使用帮助。
例子：
您可以从上面的帮助中了解到这一点，因为默认帮助将使用信息作为其输出的一部分嵌入。

$ 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.

定义自己的用法信息

您可以提供您自己的用法函数或模板。像帮助一样，函数和模板可以通过方法重写：

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

版本标志

如果Version字段在根命令上设置，则Cobra将添加顶级“--version”标志。使用'--version'标志运行应用程序将使用版本模板将版本打印到标准输出。该模板可以使用该cmd.SetVersionTemplate(s string)功能进行定制。

PreRun和PostRun钩子

可以命令Run主要功能之前或之后运行函数。该PersistentPreRun和PreRun函数在Run之前被执行。PersistentPostRun并PostRun会在Run之后被执行。Persistent*Run如果子命令没有声明他们自己的函数，这些函数将被继承。这些函数按以下顺序运行：

PersistentPreRun
PreRun
Run
PostRun

PersistentPostRun
以下是使用所有这些特性的两个命令的示例。当子命令执行时，它将运行root命令的PersistentPreRun，但不运行root命令的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()
}

出现"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完成中阅读更多关于它的信息。

贡献

1、Fork仓库
2、克隆你fork的仓库到你的电脑上(git clone https://github.com/your_username/cobra && cd cobra)
3、创建您的功能分支（git checkout -b my-new-feature）
4、进行更改并添加它们（git add .）
5、提交您的更改（git commit -m 'Add some feature'）
6、推送到分支（git push origin my-new-feature）
7、创建新的pull request

License

Cobra 是在Apache 2.0许可下发布的。请参阅LICENSE.txt