Go应用构建工具(3)–cobra

1. 概述

Cobra是一个可以创建强大的现代化命令行应用的库，许多应用都使用了Cobra库构建应用，比如k8s,Hugo等；
Cobra同时也提供了一个脚手架，用来生成基于Cobra的应用框架。
Cobra是建立在commands，arguments和flags的结构上的，commands代表命令，args代表非选项参数，flags代表标志。
一个好的应用应该是易懂的，用户能够直观的与其交互，应用通常遵循这种模式：APPNAME VERB NOUN --ADJECTIVE或者APPNAME COMMAND ARG --FLAG
比如以下示例：

hugo server --port=1313git clone URL --bare

这里VERB表示动词，NOUN表示名词，ADJECTIVE表示形容词

Cobra的使用提供了两种方式：使用Cobra库或者cobra-cli脚手架
两种方式都需要先安装：

cobra库： go install github.com/spf13/cobra/cobra@latest
cobra-cli：go install github.com/spf13/cobra-cli@latest

2. 快速使用

通用结构
通常基于cobra的应用程序遵循以下的组织结构：

  ▾ appName/▾ cmd/add.goyour.gocommands.gohere.gomain.go

其中main.go文件是很简洁的，它只做一件事，就是初始化cobra：

package mainimport ("{pathToYourApp}/cmd"
)func main() {cmd.Execute()
}

快速使用

首先按照上面的组织结构创建自己的项目
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-PKTjwsCz-1675062169702)(./img/Go应用构建工具%283%29–cobra.md/img-20230116105955.png)]
在cmd/root.go添加以下代码

package cmdimport ("fmt""os""github.com/spf13/cobra"
)var rootCmd = &cobra.Command{Use:   "mycli",Short: "mycli is a cobra test code",Long:  "mycli is a cobra test code,this is long description",
}func Execute() {if err := rootCmd.Execute(); err != nil {fmt.Fprintln(os.Stderr, err)os.Exit(1)

添加main.go

package mainimport "cobrafast/cmd"func main() {cmd.Execute()
}

添加另外的命令，这里加一个version，在version.go写入以下代码：

package cmdimport ("fmt""github.com/spf13/cobra"
)var versionCmd = &cobra.Command{Use:   "version",Short: "Print the version number of mycli",Long:  "All software has versions. This is mycli's",Run: func(cmd *cobra.Command, args []string) {fmt.Println("V1.0.01")},
}func init() {rootCmd.AddCommand(versionCmd)
}

每个cobra都有一个根命令，然后它下面有很多子命令，这里的version就是其中一个子命令，使用AddCommand添加到根明了中

测试验证

cobra自动生成帮助信息

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go -h
mycli is a cobra test code,this is long descriptionUsage:mycli [flags]mycli [command]Available Commands:completion  Generate the autocompletion script for the specified shellhelp        Help about any commandversion     Print the version number of mycliFlags:-h, --help   help for mycliUse "mycli [command] --help" for more information about a command.

单个命令的帮助信息也自动生成了：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go version -h
All software has versions. This is mycli'sUsage:mycli version [flags]Flags:-h, --help   help for version

运行子命令：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$  go run main.go version
V1.0.01

运行未定义的命令：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go get
Error: unknown command "get" for "mycli"
Run 'mycli --help' for usage.
unknown command "get" for "mycli"
exit status 1

如果希望调用命令时将错误返回，可以使用RunE方法，错误信息会被Execute方法捕获
这里将version.go的versionCmd的Run字段改为RunE：

var versionCmd = &cobra.Command{Use:   "version",Short: "Print the version number of mycli",Long:  "All software has versions. This is mycli's",RunE: func(cmd *cobra.Command, args []string) error {// fmt.Println("V1.0.01")return errors.New("version error")},
}

运行子命令：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go version
Error: version error
Usage:mycli version [flags]Flags:-h, --help   help for versionversion error
exit status 1

3. 核心特性

3.1 使用flag

Cobra使用pflag解析命令行选项,Cobra中有两种类型的flag：一种是持久化的flag，一种是本地flag。

持久化flag
定义它的命令和其子命令都可以使用这个flag。
本地flag
只能在定义它的命令中使用

以下用示例来学习这个特性：
root.go新增以下代码：

var output stringfunc init() {// 根命令定义一个持久化flagrootCmd.PersistentFlags().StringVarP(&output, "output", "o", "", "output file name")
}

output这个flag是持久化的，子命令version可以使用

var versionCmd = &cobra.Command{Use:   "version",Short: "Print the version number of mycli",Long:  "All software has versions. This is mycli's",Run: func(cmd *cobra.Command, args []string) {fmt.Printf("version: V1.0.01, output: %s\n", output)},
}

测试：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go version -o test.txt
version: V1.0.01, output: test.txt
lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go version -h
All software has versions. This is mycli'sUsage:mycli version [flags]Flags:-h, --help   help for versionGlobal Flags:-o, --output string   output file name

通过-h查看帮助信息能看到，version命令多了一个Global Flags
接下来，将root.go的持久化flag改为本地flag：

func init() {// 根命令定义一个本地flagrootCmd.Flags().StringVarP(&output, "output", "o", "", "output file name")
}

此时再查看version命令的帮助信息，就会发现没有output这个flag了：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go run main.go version -h
All software has versions. This is mycli'sUsage:mycli version [flags]Flags:-h, --help   help for version

cobra还提供了一种在解析子命令前能够先解析父命令的本地flag的方式
默认情况是本地flag只能在定义它的命令上使用，但可以通过设置字段TraverseChildren,让cobra在执行目标命令先解析父命令的本地flag。
文字描述的有点拗口，官方文档说明也比较简短，下面通过实验来说明会比较容易明白。

首先修改下代码，新增一个get命令，version为它的子命令,get命令定义一个本地flag

package cmdimport ("fmt""github.com/spf13/cobra"
)var output stringvar getCmd = &cobra.Command{Use:              "get",Short:            "Print output file name of mycli",Long:             "All software has name. This is mycli's",Run: func(cmd *cobra.Command, args []string) {fmt.Printf("name: %s\n", output)},
}func init() {getCmd.Flags().StringVarP(&output, "output", "o", "mycli", "output file name")rootCmd.AddCommand(getCmd)
}

version命令代码，将version命令挂在get命令下：

var versionCmd = &cobra.Command{Use:   "version",Short: "Print the version number of mycli",Long:  "All software has versions. This is mycli's",Run: func(cmd *cobra.Command, args []string) {fmt.Printf("version: V1.0.01, output: %s\n", output)},
}
func init() {getCmd.AddCommand(versionCmd)
}

先测试下正常情况

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get version -o hello
Error: unknown shorthand flag: 'o' in -o
Usage:mycli get version [flags]Flags:-h, --help   help for versionunknown shorthand flag: 'o' in -o
lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get -o hello version
Error: unknown shorthand flag: 'o' in -o
Usage:mycli get version [flags]Flags:-h, --help   help for versionunknown shorthand flag: 'o' in -o

常规情况下，-o是父命令get的本地flag，子命令version无法使用

修改代码(这里搞不懂跟我理解的不同，先看看代码)
修改root.go,将TraverseChildren设置为true

var rootCmd = &cobra.Command{Use:              "mycli",Short:            "mycli is a cobra test code",Long:             "mycli is a cobra test code,this is long description",TraverseChildren: true,
}

然后再测试：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ go build .
lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get  -o hello version
version: V1.0.01, output: hello
lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get version -o hello
Error: unknown shorthand flag: 'o' in -o
Usage:mycli get version [flags]Flags:-h, --help   help for versionunknown shorthand flag: 'o' in -o

这时，使用命令如./cobrafast get -o hello version，version命令就能先解析了get命令的本地flag了。
::: danger 注意
在这一块，我有几个点不是很能理解~

按照我的理解，应该是子命令里将TraverseChildren设置为true后，执行该命令时能解析父命令的flag才是，但实质上并不是，而是在root命令里添加；
基于上一点的问题，查看源码中判断TraverseChildren的地方，是在方法：ExecuteC中，有以下代码：

var flags []stringif c.TraverseChildren {cmd, flags, err = c.Traverse(args)} else {cmd, flags, err = c.Find(args)}

这个方法的调用链是这样的：Execute()-> ExecuteC(),因为我们只在root.go中调用了Execute()方法，因而才需要在rootCmd中添加

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

也许是我个人理解的不对，希望有知道的朋友能告诉我哈
3. 对于命令的执行我也是有点不理解，我以为是可以将-o写在version命令之后，实则是不行，必须要在父命令后跟上父命令的本地flag，在写上子命令才可以成功执行。
:::

3.2 将flag绑定到配置

cobra使用的配置包是viper，我们可以将flag绑定到viper，这一部分与在viper中绑定flag是一样的了。

首先新建一个配置文件，config/config.yaml

the_author: zhangsan

修改root.go，添加viper的初始化

func initViper() {viper.SetConfigName("config")viper.SetConfigType("yaml")viper.AddConfigPath("./config")if err := viper.ReadInConfig(); err != nil {fmt.Fprintln(os.Stderr, err)os.Exit(1)}
}
func init() {cobra.OnInitialize(initViper)
}

在get命令中绑定flag到viper,在执行命令时打印

var output string
var author stringvar getCmd = &cobra.Command{Use:   "get",Short: "Print output file name of mycli",Long:  "All software has name. This is mycli's",Run: func(cmd *cobra.Command, args []string) {fmt.Printf("name: %s, author: %s\n", output, viper.GetString("the_author"))},
}func init() {getCmd.Flags().StringVarP(&output, "output", "o", "mycli", "output file name")getCmd.PersistentFlags().StringVar(&author, "author", "lucas", "Author name for copyright attribution")viper.BindPFlag("the_author", getCmd.PersistentFlags().Lookup("author"))rootCmd.AddCommand(getCmd)
}

运行测试

没有指定flag时,读取的是配置文件的数据

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get
name: mycli, author: zhangsan

指定–author时，读取的是命令行的值

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get --author lisi
name: mycli, author: lisi

将配置文件的数据注释,也不指定–author，读取的就是定义flag设置的默认值了

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get
name: mycli, author: lucas

3.3 设置flag为必选

默认情况下，flag是可选的，如果希望在某个flag没有被设置时候报错，则可以将它标记为必选的，使用MarkFlagRequired()或MarkPersistentFlagRequired()
比如将output标记为必选的：

func init() {getCmd.Flags().StringVarP(&output, "output", "o", "mycli", "output file name")getCmd.PersistentFlags().StringVar(&author, "author", "lucas", "Author name for copyright attribution")getCmd.MarkFlagRequired("output")// getCmd.MarkPersistentFlagRequired("author")viper.BindPFlag("the_author", getCmd.PersistentFlags().Lookup("author"))rootCmd.AddCommand(getCmd)
}

那么在运行时，没有指定–output或-o，则会报错：

lucas@Z-NB-0406:~/workspace/test/cobra_fast$ ./cobrafast get
Error: required flag(s) "output" not set
Usage:mycli get [flags]mycli get [command]Available Commands:version     Print the version number of mycliFlags:--author string   Author name for copyright attribution (default "lucas")-h, --help            help for get-o, --output string   output file name (default "mycli")Use "mycli get [command] --help" for more information about a command.required flag(s) "output" not set

3.4 flags组

如果有不同的标志，必须一起提供(例如，–username标志，必须提供–password标志)，那么Cobra可以强制要求，使用MarkFlagsRequiredTogether()
如果有不同的标志，是互斥的，不能同时提供，比如输出格式只能是–json或–yaml，不能同时设置的情况，可以使用MarkFlagsMutuallyExclusive()

对于这两种情况：

所有的本地flag和持久化flag都可以使用

一个flag可以出现在多个组中

一个组可以包含任意个flag

3.5 位置参数和自定义参数

在命令中，除了flag标志外，通常也会有参数Arg，并且有时需要对这些参数进行验证，cobra提供了一些内置的验证函数：

NoArgs: 如果存在任何的参数，将会报错
ArbitaryArgs：接受任意参数
MinimumNArgs(int)：接受至少N个参数，否则报错
MaximumNArgs(int)：接受至多N个参数，否则报错
ExactArgs(int)：只接收N个参数，如果个数不对，报错
RangeArgs(min, max)：参数个数在min和max之间，否则报错
OnlyValidArgs：如果没有一个参数是符合command的ValidArgs字段指定的参数的话，就报错；这个要配合ValidArgs使用
MatchAll：这个方法可以组合上面几种验证函数，比如可以要求参数个数必须为2个，而且需要满足指定的参数

var getCmd = &cobra.Command{Use:   "get",Short: "Print output file name of mycli",Long:  "All software has name. This is mycli's",Run: func(cmd *cobra.Command, args []string) {fmt.Printf("name: %s, author: %s\n", output, viper.GetString("the_author"))},ValidArgs: []string{"hello", "word"},Args:      cobra.MatchAll(cobra.ExactArgs(2), cobra.OnlyValidArgs),
}

也可以自定义验证函数，实现方法：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 cobraif err := cobra.MinimumNArgs(1)(cmd, args); err != nil {return err}// Run the custom validation logicif 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!")},
}

3.6 钩子函数:PreRun和PostRun

cobra提供了一些钩子函数，在运行命令的Run函数时，PersistentPreRun和PreRun函数会在Run函数执行之前执行，PersistentPostRun和PostRun函数会在Run函数执行之后执行。
对于带有Persistent的函数，如果它的子命令没有实现这个函数，那么子命令将会继承父命令的Persistent*Run方法
这些钩子函数的执行顺序如下：

PersistentPreRun
PreRun
Run
PostRun
PersistentPostRun

package mainimport ("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]

3.7 其他特性

cobra还支持其他比较有用的特性，比如：自定义Help命令，自定义帮助信息，添加–version标志，输入无效命令时的建议等,还可以生成命令的相关文档…