# golang命令行库Cobra的使用 ## 摘要 Cobra提供简单的接口来创建强大的现代化CLI接口，非常多知名的开源项目使用了 cobra 库构建命令行，如Kubernetes、Hugo、etcd等 ## cobra提供的功能 - 简易的子命令行模式，如 hugo server， hogo fetch等等 - 完全兼容posix命令行模式 - 嵌套子命令subcommand - 支持全局，局部，串联flags - 使用Cobra很容易的生成应用程序和命令，使用cobra create app和cobra add subname - 如果命令输入错误，将提供智能建议，如 hugo srver，将提示srver没有，是否是hugo server - 自动生成commands和flags的帮助信息 - 自动生成详细的help信息，如app help - 自动识别-h，--help帮助flag - 自动生成应用程序在bash下命令自动完成功能 - 自动生成应用程序的man手册 - 命令行别名 - 灵活定义help和usage信息 - 可选的紧密集成的[viper](https://github.com/spf13/viper) apps ## 概念 Cobra是建立在结构的命令、参数和标志之上。 - 命令（command） 表示 操作 - 标志（flags) 用来控制命令（command）的具体行为 - 参数（args） 最好的应用程序就像读取句子。用户会知道如何使用本机应用程序，因为他们将理解如何使用它。 比如下面的例子，`server`是命令，`port`是标志: ``` hugo server --port=1111 ``` ## 相关操作 ### 安装 使用Cobra很简单。首先，使用`go get`安装最新版本 ``` go get github.com/spf13/cobra/cobra ``` 将cobra下载完成后，GOPATH/bin目录会生成一个cobra可执行程序，通过这个程序我们可以初始化一个cobra代码框架。 ### 初始化一个项目 ``` C:\Users\xx\Desktop\git\cobra>go mod init times C:\Users\xx\Desktop\git\cobra>cobra init --pkg-name times 或者 cobra init --pkg-name github.com/spf13/newApp 或者 cobra init --pkg-name github.com/spf13/newApp path/to/newApp ``` 初始化之后可以看到，cobra命令在项目目录底下创建了开发框架： ![image-20210729165212791](https://xieys.club/images/posts/image-20210729165212791.png) > root.go代码中有一个rootCmd变量 - l Use: 命令。 - l Short： 命令的简短描述。 - l Long： 命令的详细描述,在帮助命令，如$ [appName] -h或者$ [appName] [command] -h时会显示此程序和此命令的字符串。 - l Run: 命令执行入口，函数主要写在这个模块中。 - l 函数initConfig(): 用来初始化viper配置文件位置，监听变化。 - l 函数init(): 定义flag和配置处理。 ### 通过cobra命令添加子命令 ``` 在上面创建的项目基础上添加子命令 C:\Users\xx\Desktop\git\cobra>cobra add show ``` 此时，cmd目录会多一个show.go的文件，我们可以在这个文件中定义show具体执行的操作，这里的show就是上面说的**概念里说的command（命令）**。 #### 使用标志 标志（flags）用来控制command的具体行为。根据选项的作用范围，可以把选项分为两类： >persistent 全局 对于persistent类型的选项，即可以设置给该Command，又可以设置给该Command的子Command。对于一些全局性的选项，比较适合设置为persistent类型，比如控制输出的verbose选项。 > local 局部 Cobra默认只在目标命令上解析标志，父命令忽略任何局部标志。通过打开`Command.TraverseChildren` Cobra将会在执行任意目标命令前解析标志 示例： ``` var ( //Foo = new(string) //Print string //Show bool showL bool PrintL string FooL = new(string) ) func init() { //下面定义了一个Flag foo，foo后面接的值会被赋值给Foo //Foo = testCmd.PersistentFlags().String("foo","","A help foo") ////下面定义了一个Flag print，print后面的值会被赋值给Print变量 //testCmd.PersistentFlags().StringVar(&Print,"print","","print") ////下面定义了一个Flag show，show默认为false，有两种调用方式 --show \ -s ，命令后面接了show则上面定义的show变量就会变成true //testCmd.PersistentFlags().BoolVarP(&Show,"show","s",false,"show") // 下面定义了一个Flag show，show默认为false，两种条用方式 --show\-s ，命令后面接了show则上面定义的show变量就会变成true showL = *testCmd.Flags().BoolP("showL", "S", false, "show") // 下面定义了一个Flag print ,print后面的值会被赋值给Print变量 testCmd.Flags().StringVar(&PrintL, "printL", "", "print") // 下面定义了一个Flag foo, foo后面接的值会被赋值给Foo FooL = testCmd.Flags().String("fooL", "", "A help for foo") rootCmd.AddCommand(testCmd) } ``` #### 必须的标记 默认情况下的选项都是可选的，但一些用例要求用户必须设置某些选项，这种情况cobra也是支持的，通过command的MarkFlagRequired方法标记该选项即可 ``` 全局标记设置方法 rootCmd.PersistentFlags().StringVar(&Region,"region","r","","AWS region (required)") rootCmd.MarkPersistentFlagRequired("region") 局部标记设置方法 rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)") rootCmd.MarkFlagRequired("region") ``` #### 位置参数 cobra默认提供了一些验证方法： 1、NoArgs - 如果存在任何位置参数，该命令将报错 2、ArbitraryArgs - 该命令会接受任何位置参数 3、OnlyValidArgs - 如果有任何位置参数不在命令ValidArgs字段中，该命令将报错 4、MinimumNArgs(int) - 至少要有N个位置参数，否则报错 5、MaximumNArgs(int) - 如果位置参数超过N个将报错 6、ExactArgs(int) - 必须有N个位置参数，否则报错 7、ExactValidArgs(int) 必须有N个位置参数，且都在命令的ValidArgs字段中，否则报错 8、RangeArgs(min,max) - 如果位置参数的个数不在区间min和max之中，报错 比如要让Command cmdTimes至少有一个位置参数，可以这样初始化它： ``` var testCmd = &cobra.Command{ Use: "test", //定义arguments数量最少为1个 Args: cobra.MinimumNArgs(1), Short: "short usage", Long: `long usage`, Run: func(cmd *cobra.Command, args []string) { if showL{ fmt.Println("Show") } fmt.Println("Print",PrintL) fmt.Println("Foo",*FooL) }, } ``` #### 简单示例 这里就不使用脚手架，直接使用导入 ``` 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() } ``` ### help命令 当你的程序有子命令时，Cobra 会自动给你程序添加help命令。当你运行‘app help’，会调用help命令。另外，help同样支持其它输入命令。例如，你有一个没有任何其它配置的命令叫‘create’，当你调用‘app help create’ Corbra 将会起作用。 #### 例子 下面的输入是 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 就跟其它命令一样，并没有特殊的逻辑或行为。事实上，你也可以提供你自己help如果你想的话。 #### 自定制help 你能为默认的命令，提供你自己的help命令或模板。使用下面的方法: ``` cmd.SetHelpCommand(cmd *Command) cmd.SetHelpFunc(f func(*Command, []string)) cmd.SetHelpTemplate(s string) ``` 后2个也将适用于任何子命令 #### 使用信息 当用户提供无效的标记或命令，Cobra 将会返回`用法`。 #### 列子 ``` C:\Users\xx\Desktop\git\devops>cobra --ss Error: unknown flag: --ss 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. ``` #### 自定制使用信息 你能提供你自己的用法函数或模板给 Cobra 使用。 比如帮助，方法和模板都可以重写。 ``` cmd.SetUsageFunc(f func(*Command) error) cmd.SetUsageTemplate(s string) ``` ### 版本标记 如果Version字段设置到了根命令，Cobra 会提供了一个顶层 ‘--version’标记。运行带上‘--version’标记的程序，将会按照模板版本信息。模板可以通过`cmd.SetVersionTemplate(s string)`方法修改 ### 运行前和运行后的钩子 在命令运行前或运行后，再运行方法非常容易。`PersistentPreRun`和`PreRun`方法将会在`Run`之前执行。`PersistentPostRun`和`PostRun`方法将会在`Run`之后执行。`Persistent*Run`方法会被子命令继承，如果它们自己没有定义的话。这些方法将按照下面的属性执行： - `PersistentPreRun` - `PreRun` - `Run` - `PostRun` - `PersistentPostRun` 下面的例子，2个命令都使用了上面的特性。当子命令执行的时候，它将执行根命令的`PersistentPreRun`，但不会执行根命令的`PersistentPostRun`： ```go 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] ``` ### 处理“未知命令” 的建议 Cobra 会自动输出建议，当遇到“unknown command”错误时。这使得当输入错误时， Cobra 的行为类似`git`命令。例如： ``` $ hugo srever Error: unknown command "srever" for "hugo" Did you mean this? server Run 'hugo --help' for usage. ``` 建议会基于注册的子命令自动生成。使用了[Levenshtein distance](http://en.wikipedia.org/wiki/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](https://github.com/spf13/cobra/blob/master/doc/md_docs.md) - [ReStructured Text](https://github.com/spf13/cobra/blob/master/doc/rest_docs.md) - [Man Page](https://github.com/spf13/cobra/blob/master/doc/man_docs.md)