go命令行库-cobra
Cobra介绍
Cobra 是一个用于创建强大的现代 CLI 应用程序的库。几乎包含了你所需要的所有元素。
Cobra 用于许多 Go 项目，例如Kubernetes、Docker、GitHub CLI、Hugo等等。
Cobra提供：
- 简单的基于子命令的 CLI：app server、app fetch等。
- 完全符合 POSIX 的标志（包括短版和长版）
- 嵌套子命令
- 全局、本地和级联标志
- 明智的建议（app srver…你的意思是app server？）
- 命令和标志的自动帮助生成
- 子命令的分组帮助
- -h,–help等的自动帮助标志识别
- 为您的应用程序自动生成 shell 自动补全的功能（bash、zsh、fish、powershell）
- 为您的应用程序自动生成的手册页（man page）
- 命令别名，这样您就可以在不破坏它们的情况下进行更改
- 定义您自己的帮助、使用等的灵活性。
- 可选与viper无缝集成，用于 12 要素应用程序（viper是作者的另一个项目，用来给go语言程序提供配置解决方案，可以将cobra和viper结合使用）
Cobra安装
cobra提供了用于go get安装的最新版本的库。
go get -u github.com/spf13/cobra@latest同时，Cobra提供了一个方便的命令行程序生成器cobra-cli，后续我们会使用cobra-cli来自动生成模板，简化我们的工作。因此也需要安装它。
go install github.com/spf13/cobra-cli@latest需要注意的是，Go 会自动将cobra-cli安装在你的GOPATH/bin目录中，因此你要确保GOPATH/bin被你添加到了环境变量中。否则你无法使用cobra-cli程序。以Debian系统为例，你可以通过go env|grep GOPATH命令来查看你的GOPATH，然后将GOPATH/bin添加到~/.bashrc文件中，例如：
export PATH=$PATH:/home/zy/go/bin在~/.bashrc中添加上面这行之后，执行下面的命令，使其生效。
source ~/.bashrcCobra使用
Cobra提供了一个生成器（cobra-cli），可以用来初始化你的命令行程序。这是将 Cobra 整合到您的应用程序中的最简单方法。当然你也可以手动来创建自己的命令行程序。cobra-cli只是帮助你简化了创建过程。下面使用cobra-cli生成器来创建我们自己的命令行程序。
创建一个新目录并初始化go mod
mkdir mycmd cd mycmd go mod init mycmd
使用cobra-cli来初始化一个项目
确保你以及按照安装步骤安装了cobra以及cobra-cli，并将cobra-cli添加到了环境变量中。在mycmd目录下执行下面的命令。
cobra-cli init执行该命令会在当前目录下生成cmd目录，main.go等文件。现在尝试运行一下自动生成的命令行程序。
go run main.go确保可以成功运行即可
修改自动生成的程序为你自己的功能
使用cobra-cli生成以后，目录结构如下所示。
.
├── cmd
│ └── root.go
├── go.mod
├── go.sum
├── LICENSE
└── main.go我们来看一下自动生成的文件中的内容。由于我们在自动生成的时候，没有使用-l(–license)参数，因此自动生成的LICENSE文件为空。main.go文件和cmd目录下的root.go才是我们关心的重点。
// main.go
package main
import "mycmd/cmd"
func main() {
cmd.Execute()
}main.go文件非常简单，就只是简单的初始化cobra。让我们再来看看root.go文件。
// root.go
package cmd
import (
"os"
"github.com/spf13/cobra"
)
// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
Use: "mycmd",
Short: "A brief description of your application",
Long: `A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:
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.`,
// Uncomment the following line if your bare application
// has an action associated with it:
// Run: func(cmd *cobra.Command, args []string) { },
}
// Execute adds all child commands to the root command and sets flags appropriately.
// This is called by main.main(). It only needs to happen once to the rootCmd.
func Execute() {
err := rootCmd.Execute()
if err != nil {
os.Exit(1)
}
}
func init() {
// Here you will define your flags and configuration settings.
// Cobra supports persistent flags, which, if defined here,
// will be global for your application.
// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.mycmd.yaml)")
// Cobra also supports local flags, which will only run
// when this action is called directly.
rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}首先是定义一个cobra.Command指针类型的变量rootCmd，其中定义了Use，Short, Long字段的值，关于这些字段的含义，可以通过查看Command结构体的注释来了解。另外就是在init函数中，给rootCmd添加了一个标志toggle。Execute()函数就是我们在main.go文件中调用的函数。现在，我们来修改一下root.go程序。让其展示我们的功能。
// 修改后的root.go
package cmd
import (
"os"
"github.com/spf13/cobra"
)
var rootCmd = &cobra.Command{
Use: "test",
Short: "A test programming",
Long: "A test programming",
Run: func(cmd *cobra.Command, args []string) {
cmd.Help() // 当不带有任何参数或者标志执行程序的时候，输出help
},
}
func Execute() {
err := rootCmd.Execute()
if err != nil {
os.Exit(1)
}
}
func init() {
rootCmd.CompletionOptions.DisableDefaultCmd = true // 禁用Completion命令
rootCmd.Version = "0.0.1" // 设置version
}执行main.go，输出如下所示：
A test programming
Usage:
test [flags]
Flags:
-h, --help help for test
-v, --version version for test我们加上标志-v(go run main.go -v)再来执行一次，输出如下：
test version 0.0.1我们通过rootCmd.CompletionOptions.DisableDefaultCmd = true这行代码禁用掉了completion命令。它可以提供生成shell completion，来给予命令补全等功能。详细的文档可以查看Generating shell completions
增加新命令
初始化 cobra 应用程序后，你可以继续使用cobra-cli向应用程序添加其他命令。执行此操作的命令是cobra-cli add [command]，例如：
cobra-cli add start执行该命令之后，你会发现在cmd目录下生成了一个名为start.go的文件，内容如下所示：
// start.go
package cmd
import (
"fmt"
"github.com/spf13/cobra"
)
// startCmd represents the start command
var startCmd = &cobra.Command{
Use: "start",
Short: "A brief description of your command",
Long: `A longer description that spans multiple lines and likely contains examples
and usage of using your command. For example:
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.`,
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("start called")
},
}
func init() {
rootCmd.AddCommand(startCmd)
// Here you will define your flags and configuration settings.
// Cobra supports Persistent Flags which will work for this command
// and all subcommands, e.g.:
// startCmd.PersistentFlags().String("foo", "", "A help for foo")
// Cobra supports local flags which will only run when this command
// is called directly, e.g.:
// startCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}这段代码也很容易理解，startCmd这个结构体指针中配置了结构体中的一些参数；init函数中rootCmd.AddCommand(startCmd)这行代码将startCmd作为一个命令添加到rootCmd中。此时默认的父级就是rootCmd。还可以使用-p标志直接指定父命令。例如:
cobra-cli add time -p "startCmd"需要注意的是：“指定父级时，请确保与代码中使用的变量名匹配”。这样生成的time.go文件如下所示：
// time.go
package cmd
import (
"fmt"
"github.com/spf13/cobra"
)
// timeCmd represents the time command
var timeCmd = &cobra.Command{
Use: "time",
Short: "A brief description of your command",
Long: `A longer description that spans multiple lines and likely contains examples
and usage of using your command. For example:
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.`,
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("time called")
},
}
func init() {
startCmd.AddCommand(timeCmd)
// Here you will define your flags and configuration settings.
// Cobra supports Persistent Flags which will work for this command
// and all subcommands, e.g.:
// timeCmd.PersistentFlags().String("foo", "", "A help for foo")
// Cobra supports local flags which will only run when this command
// is called directly, e.g.:
// timeCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}可以看到init函数中是把timeCmd添加到startCmd，而不是之前的start命令，会把startCmd添加到rootCmd。这样，我们可以这样执行命令。
go run main.go start time还有一点需要注意，那就是命令的命令需要遵循驼峰命名法。
编辑 cmd 中的文件并为您的应用程序自定义它们 在第三步的时候，我们已经介绍过了简单的方式来自定义它们。下面对command中常用的参数做一个说明。
参数 | 含义 |
|---|---|
Use | 显示用法，例如：add [-F file |
Short | 是help中输出的简短描述 |
Long | 是help中输出的长描述 |
Example | 如何使用该命令的示例 |
Aliases | 别名数组，用来给命令起别名 |
GroupID | 该子命令在其父命令的help标志输出中分组时使用的组id |
Arg | 参数 |
Version | 版本标志。如果该值非空，并且命令没有定义Version标志，则Version标志将被添加到命令中，如果定义了Version标志，将打印Version变量的内容。如果命令没有定义一个简写的“v”标志，也将添加简写的“v”标志。 |
Run | 通常是实际的功函数，即使用该命令的时候会调用的函数。函数原型func(cmd *Command, args []string) |
RunE | 和Run类似，只不过会返回一个error，函数原型func(cmd *Command, args []string) error |
使用标志
由于标志是在不同的位置定义和使用的，我们需要在外部定义一个具有正确范围的变量来分配标志以使用。例如：
var Verbose bool
var Source string分配标志有两种不同的方法。
持久标志
标志可以是“持久的”，这意味着该标志将可用于分配给它的命令以及该命令下的每个命令。对于全局标志，将标志分配为根上的持久标志。
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")本地标志
也可以在本地分配一个标志，该标志仅适用于该特定命令。
localCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")父命令上的本地标志
默认情况下，Cobra 仅解析目标命令上的本地标志，而忽略父命令上的任何本地标志。通过启用Command.TraverseChildren，Cobra 将在执行目标命令之前解析每个命令上的本地标志。
command := cobra.Command{
Use: "print [OPTIONS] [COMMANDS]",
TraverseChildren: true,
}必需的标志
默认情况下，标志是可选的。相反，如果您希望您的命令在未设置标志时报告错误，请将其标记为必需：
rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkFlagRequired("region")或者，对于持久标志：
rootCmd.PersistentFlags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkPersistentFlagRequired("region")标记组
如果您有不同的标志必须一起提供（例如，如果他们提供–username标志，他们也必须提供–password标志），那么 Cobra 可以强制执行该要求：
rootCmd.Flags().StringVarP(&u, "username", "u", "", "Username (required if password is set)")
rootCmd.Flags().StringVarP(&pw, "password", "p", "", "Password (required if username is set)")
rootCmd.MarkFlagsRequiredTogether("username", "password")如果它们表示互斥选项，例如将输出格式指定为其中一个–json或–yaml但从不同时指定，您还可以防止同时提供不同的标志：
rootCmd.Flags().BoolVar(&u, "json", false, "Output in JSON")
rootCmd.Flags().BoolVar(&pw, "yaml", false, "Output in YAML")
rootCmd.MarkFlagsMutuallyExclusive("json", "yaml")位置和自定义参数
可以使用Args字段来指定位置参数的验证Command。内置以下验证器：
- 参数数量：
- NoArgs- 如果有任何位置参数，则报告错误。
- ArbitraryArgs- 接受任意数量的参数。
- MinimumNArgs(int)- 如果提供的位置参数少于 N 个，则报告错误。
- MaximumNArgs(int)- 如果提供的位置参数超过 N 个，则报告错误。
- ExactArgs(int)- 如果不完全有 N 个位置参数，则报告错误。
- RangeArgs(min, max)min- 如果 args 的数量不在 和 之间，则报告错误max。
- 参数内容： 如果在OnlyValidArgsValidArgs字段中未指定任何位置参数，则报告错误Command，可以选择将其设置为位置参数的有效值列表。如果Args未定义或nil，则默认为ArbitraryArgs。
此外，MatchAll(pargs …PositionalArgs)可以将现有检查与任意其他检查相结合。例如，如果你想在不完全有 N 个位置参数的情况下报告错误，或者如果有任何位置参数不在 的ValidArgs字段中Command，你可以调用and MatchAll，如下所示：ExactArgsOnlyValidArgs
var cmd = &cobra.Command{
Short: "hello",
Args: cobra.MatchAll(cobra.ExactArgs(2), cobra.OnlyValidArgs),
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("Hello, World!")
},
}另外，你可以设置任何满足func(cmd *cobra.Command, args []string) error. 例如：
var cmd = &cobra.Command{
Short: "hello",
Args: func(cmd *cobra.Command, args []string) error {
// Optionally run one of the validators provided by cobra
if err := cobra.MinimumNArgs(1)(cmd, args); err != nil {
return err
}
// Run the custom validation logic
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!")
},
}关于cobra库的更多使用指南，请参考该项目的官方文档
参考资料
- https://github.com/spf13/cobra/blob/main/README.md