社区微信群开通啦，扫一扫抢先加入社区官方微信群
社区微信群
点击上方“朱小厮的博客”，选择“设为星标”
回复”1024“获取独家整理的学习资料
这篇文章是分析golang中命令行解析库的。关注我公众号的很多都是Java程序员，对于Java而言，有很多命令行解析库，如：JOpt Simple、Commons CLI、JCommander，javaer也可以看看类比一下两种语言不同解析的差异。
Cobra在golang项目里面应用非常的广泛，比如kubernetes、docker、openshift、Hugo等都用到了Cobra，如果要熟悉这些go开源项目实现的话，Cobra是必不可少的掌握项。
Cobra既是用于创建强大的现代CLI应用程序的库，也是用于生成应用程序和命令文件的程序。
Cobra提供的功能：
简易的子命令行模式，如 app server， app fetch等等
完全兼容posix命令行模式
嵌套子命令subcommand
支持全局，局部，串联flags
使用Cobra很容易的生成应用程序和命令，使用cobra create appname和cobra add cmdname
如果命令输入错误，将提供智能建议，如 app srver，将提示srver没有，是否是app server
自动生成commands和flags的帮助信息
自动生成详细的help信息，如app help
自动识别-h，--help帮助flag
自动生成应用程序在bash下命令自动完成功能
自动生成应用程序的man手册
命令行别名
自定义help和usage信息
可选的紧密集成的viper apps
(Cobra是眼镜蛇的意思。Steve Francia这位大佬取名真是diao，还有个项目叫viper。。)
Cobra是建立在结构的命令、参数和标志之上。命令（Commands）代表操作，参数（Args）和标志（Flags）是这些行动的修饰符。最好的应用程序就像读取句子。用户会知道如何使用本机应用程序，因为他们将理解如何使用它。
要遵循的模式是
APPNAME VERB NOUN --ADJECTIVE
或
APPNAME COMMAND ARG --FLAG
命令是应用程序的中心点。应用程序支持的每个交互都将包含在命令中。命令可以具有子命令并可选地运行动作。
标志是一种修改命令行为的方法。Cobra支持完全符合POSIX标准的标志以及Go 标志包。Cobra命令可以定义持久保存到子命令和标志的标志，这些命令和标志仅对该命令可用。标志功能由pflag库提供，pflag库是标准库的一个分支，它在添加POSIX兼容性时保持相同的接口。
Github地址: https://github.com/spf13/cobra
使用Cobra很简单。首先，使用go get安装最新版本
go get github.com/spf13/cobra/cobra
由于各种问题，国内使用 go get 安装 golang 官方包可能会失败。如果出现：
hidden@hidden:~$ go get github.com/spf13/cobra/cobra
package golang.org/x/sys/unix: unrecognized import path "golang.org/x/sys/unix" (https fetch: Get https://golang.org/x/sys/unix?go-get=1: dial tcp 216.239.37.1:443: connect: connection timed out)
package golang.org/x/text/transform: unrecognized import path "golang.org/x/text/transform" (https fetch: Get https://golang.org/x/text/transform?go-get=1: dial tcp 216.239.37.1:443: connect: connection timed out)
package golang.org/x/text/unicode/norm: unrecognized import path "golang.org/x/text/unicode/norm" (https fetch: Get https://golang.org/x/text/unicode/norm?go-get=1: dial tcp 216.239.37.1:443: connect: connection timed out)
即使使用代理也不行，怎么解决这个问题？
其实 golang 在 github 上建立了一个镜像库，如 https://github.com/golang/sys/， 即是 https://golang.org/x/sys/ 的镜像库。要避免以上报错，其实只需要执行以下步骤：
mkdir -p $GOPATH/src/golang.org/x
cd $GOPATH/src/golang.org/x
git clone https://github.com/golang/sys
git clone https://github.com/golang/text
然后再执行go get github.com/spf13/cobra/cobra即可。
安装成功之后会生成一个名为cobra的可执行文件：
hidden@hidden:~$ ls -al $GOPATH/bin | grep cobra
-rwxr-xr-x 1 zhuzhonghua zhuzhonghua 11411056 Aug 12 15:48 cobra
假设现在我们要开发一个基于CLI的命令程序，名字为demo。执行如下命令：
hidden@hidden:~$ cd $GOPATH/src/github.com/spf13/
hidden@hidden:~/go/src/github.com/spf13$ cobra init demo --pkg-name=github.com/spf13/demo
Your Cobra applicaton is ready at
/home/zhuzhonghua/go/src/github.com/spf13/demo
hidden@hidden:~/go/src/github.com/spf13$ cd demo/
在$GOPATH/src/github.com/spf13目录下会生成一个demo的文件夹，结构如下：
hidden@hidden:~/go/src/github.com/spf13/demo$ tree
.
├── cmd
│ └── root.go
├── LICENSE
└── main.go
1 directory, 3 files
在demo目录下会有如下的内容：
hidden@hidden:~/cobra/demo$ tree
.
├── cmd
│ └── root.go
├── LICENSE
└── main.go
1 directory, 3 files
测试cobra效果：
hidden@hidden:~/cobra/demo$ go run main.go
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.
subcommand is required
exit status 1
在Cobra应用程序中，通常main.go文件非常空洞。它主要只干一件事：初始化Cobra。
package main
//import "{pathToYourApp}/cmd"
import "github.com/spf13/demo/cmd"
func main() {
cmd.Execute()
}
可以定义其他命令，并且通常在cmd/目录中为每个命令提供自己的文件。
如果要创建版本（version）命令，可以创建cmd/version.go并使用以下内容填充它：
hidden@hidden:~/go/src/github.com/spf13/demo$ cobra add version
version created at /home/zhuzhonghua/go/src/github.com/spf13/demo
此目录结构变更为：
hidden@hidden:~/go/src/github.com/spf13/demo$ tree
.
├── cmd
│ ├── root.go
│ └── version.go
├── LICENSE
└── main.go
1 directory, 4 files
现在我们来执行以下这个子命令：
hidden@hidden:~/go/src/github.com/spf13/demo$ go run main.go version
version called
生成的version代码如下（cmd/version.go）：
package cmd
import (
"fmt"
"github.com/spf13/cobra"
)
// versionCmd represents the version command
var versionCmd = &cobra.Command{
Use: "version",
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("version called")
},
}
func init() {
rootCmd.AddCommand(versionCmd)
// Here you will define your flags and configuration settings.
// Cobra supports Persistent Flags which will work for this command
// and all subcommands, e.g.:
// versionCmd.PersistentFlags().String("foo", "", "A help for foo")
// Cobra supports local flags which will only run when this command
// is called directly, e.g.:
// versionCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}
注：命令的名称使用驼峰式命名（camelCase），而不能使用蛇形命名（snake_case）。读者可以自行创建一个蛇形命名的命令来查看一下实际的效果（hint: camelCase to snake_case）。
修改上面代码中的函数Run：
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("version called")
},
修改为：
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("Version 1.0.0 for demo")
},
再次执行go run main.go version，结果如下：
Version 1.0.0 for demo
在上面的cmd/version.go中我们发现在init函数有这么一行代码：rootCmd.AddCommand(versionCmd)，这个rootCmd是什么呢？
package cmd
import (
"fmt"
"os"
"github.com/spf13/cobra"
homedir "github.com/mitchellh/go-homedir"
"github.com/spf13/viper"
)
var cfgFile string
// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
Use: "demo",
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() {
if err := rootCmd.Execute(); err != nil {
fmt.Println(err)
os.Exit(1)
}
}
func init() {
cobra.OnInitialize(initConfig)
// 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/.demo.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")
}
// initConfig reads in config file and ENV variables if set.
func initConfig() {
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 ".demo" (without extension).
viper.AddConfigPath(home)
viper.SetConfigName(".demo")
}
viper.AutomaticEnv() // read in environment variables that match
// If a config file is found, read it in.
if err := viper.ReadInConfig(); err == nil {
fmt.Println("Using config file:", viper.ConfigFileUsed())
}
}
打开cmd/root.go（上面的示例代码），你会发现rootCmd其实就是我们的根命令。我相信机智的同学已经猜出来我们添加子命令的子命令的方法了。现在让我们在cmd目录下新建help.go文件，项目文件结构为：
hidden@hidden:~/go/src/github.com/spf13/demo$ tree
.
├── cmd
│ ├── help.go
│ ├── root.go
│ └── version.go
├── LICENSE
└── main.go
1 directory, 5 files
其中cmd/help.go的内容为(help为version的子命令)：
package cmd
import (
"fmt"
"github.com/spf13/cobra"
)
// versionCmd represents the version command
var helpCmd = &cobra.Command{
Use: "help",
Short: "show command info",
Long: `<snip>`,
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("Here is the help information")
},
}
func init() {
versionCmd.AddCommand(helpCmd) //注意这里是verisonCmd不是rootCmd
}
执行go run main.go version help命令之后，结果为：
hidden:demo hidden$ go run main.go version help
Here is the help information
Flags提供了修饰符来控制动作命令的操作。
Persistent Flags：全局性flag, 可用于它所分配的命令以及该命令下的每个命令。在根上分配标志作为全局flag。
Local Flags：局部性flag,在本args分配一个标志，该标志仅适用于该特定命令。
Required flags：必选flag，flag默认是可选的。如果希望命令在未设置flag时报告错误，请将其标记为required。
如果仔细看过上面cmd/version.go中init函数中的注释的话，你应该已经得到了足够多的信息来自己操作添加flag。
不过这里我再解释一下，首先是persistent参数，当你的参数作为persistent flag存在时，如注释所言，在其所有的子命令之下该参数都是可见的。而local flag则只能在该命令调用时执行。
可以做一个简单的测试，在cmd/version.go的init函数中，添加如下内容(添加在rootCmd.AddCommand(versionCmd)这一行之上):
versionCmd.PersistentFlags().String("global_foo", "global_val", "A help for global_foo")
versionCmd.Flags().String("local_foo","local_val", "A help for local_foo")
现在运行go run main.go version -h得到如下结果：
hidden:demo hidden$ go run main.go version -h
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.
Usage:
demo version [flags]
demo version [command]
Available Commands:
help show command info
Flags:
--global_foo string A help for global_foo (default "global_val")
-h, --help help for version
--local_foo string A help for local_foo (default "local_val")
Global Flags:
--config string config file (default is $HOME/.demo.yaml)
Use "demo version [command] --help" for more information about a command.
接着我们对比着再运行go run main.go help -h试试：
hidden:demo hidden$ go run main.go version help -h
<snip>
Usage:
demo version help [flags]
Flags:
-h, --help help for help
Global Flags:
--config string config file (default is $HOME/.demo.yaml)
--global_foo string A help for global_foo (default "global_val")
可以发现在Gloabal Flags的变化。version作为root的子命令，仍然可以使用root的persistent flag-> config（可以查看root.go），而help作为test的子命令，不仅可以使用test的persistent flag-> fool, 也可以使用test父命令的persistent flag。从而我们可以直观的看出persistent的作用范围是该命令之后的所有子命令。
flag支持的参数类型可以参考文档：https://godoc.org/github.com/spf13/cobra
注意：cmd.Flags().String()与 cmd.Flags().StringP()是不一样的。假如我们在version.go的init下增加如下两行:
versionCmd.Flags().String("flag1","", "flag1 usage")
versionCmd.Flags().StringP("flga2","f","", "flag2 usage")
前者调用需要如下形式：
go run main.go version --flag1
后者有如下两种形式调用：
go run main.go version --flag2
go run main.go version -f
其它示例：
persistent flag:
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")
local flag:
rootCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")
rootCmd.MarkFlagRequired("source") // Flags默认是可选的。如果您希望命令在未设置Flags时报告错误，请将其标记为必需
在知道了如何设置参数后，我们的下一步当然是需要在运行时获取改参数的值。现在我们把注意力放到version.go的这个部分：
var versionCmd = &cobra.Command{
Use: "version",
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("Version 1.0.0 for demo")
},
}
让我们把注意力重新放到上面的代码上。我们也很容易可以猜测到Use,Short,Long三个参数的作用，这里便不做阐述。
显而易见，我们应该在Run这里来获取参数并执行我们的命令功能。获取参数其实也并不复杂。以versionCmd.Flags().StringP("flag2", "f", "", "flag2 usage")此为例，我们可以在Run函数里添加：
str,_ := cmd.Flags().GetString("flag2")
fmt.Printf("The param vale is %sn", str)
运行命令go run main.go version -f vvvv，获得结果如下：
The param vale is vvvv
Version 1.0.0 for demo
可以使用Args字段来指定位置参数的验证Command。
以下验证器内置：
NoArgs - 如果存在任何位置参数，该命令将报告错误。
ArbitraryArgs - 该命令将接受任何args。
OnlyValidArgs- 如果存在任何不在ValidArgs字段中的位置参数，该命令将报告错误Command。
MinimumNArgs(int) - 如果没有至少N个位置参数，该命令将报告错误。
MaximumNArgs(int) - 如果有多于N个位置参数，该命令将报告错误。
ExactArgs(int) - 如果没有确切的N位置参数，该命令将报告错误。
RangeArgs(min, max) - 如果args的数量不在预期args的最小和最大数量之间，则该命令将报告错误。
为了演示Args的用法，我们在cmd目录下再创建一个args.go文件，其内容如下（注意多了一个Args函数）：
mport (
"fmt"
"github.com/pkg/errors"
"github.com/spf13/cobra"
)
var argsCmd = &cobra.Command{
Use: "args",
Short: "args demo",
Long: `<snip>`,
Args: func(cmd *cobra.Command, args []string) error {
if len(args)<1{
return errors.New("requires at least one arg")
}
return nil
},
Run: func(cmd *cobra.Command, args []string) {
fmt.Println("args called, args: ", args)
},
}
func init() {
rootCmd.AddCommand(argsCmd)
}
示例中限定参数的格式至少为一个否则会报错。我们来运行一下看一看结果如何，首先是不添加参数（go run main.go args）：
hidden:demo hidden$ go run main.go args
Error: requires at least one arg
Usage:
demo args [flags]
Flags:
-h, --help help for args
Global Flags:
--config string config file (default is $HOME/.demo.yaml)
requires at least one arg
exit status 1
可以看到报错：Error: requires at least one arg。
我们再来试一下添加参数的结果：
hidden:demo hidden$ go run main.go args 1
args called, args: [1]
hidden:demo hidden$ go run main.go args 1 2 3 4
args called, args: [1 2 3 4]
示例中的Args函数可以替换为
Args: cobra.MinimumNArgs(1),
读者可以自行验证一下效果。
前面的示例中出现了cmd/help.go，为了不产生迷惑，我们把这个文件先删除掉。
当您有子命令时，Cobra会自动为您的应用程序添加一个帮助命令。当用户运行“app help”时会调用此方法。此外，帮助还将支持所有其他命令作为输入。比如说，你有一个名为'create'的命令，没有任何额外的配置; 当'app help create'被调用时，Cobra会工作。每个命令都会自动添加' - help'标志。
可以在终端输入cobra或者cobra help命令看一下实际的效果:
hidden@hidden:~$ 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”来做出响应。
示例：
hidden@hidden:~$ 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.
您可以提供自己的使用功能或模板供Cobra使用。与Help一样，函数和模板可以通过公共方法覆盖：
cmd.SetUsageFunc(f func(*Command) error)
cmd.SetUsageTemplate(s string)
我们可以在Run方法之前或者之后运行一些其它的方法（函数）。PersistentPreRun和PreRun在Run之前执行。PersistentPostRun和PostRun将Run之后执行。Persistent***Run如果子程序没有声明他们自己的功能，他们将继承这些功能。这些功能按以下顺序运行：
PersistentPreRun
PreRun
Run
PostRun
PersistentPostRun
下面是使用所有这些功能的两个命令的示例。执行子命令时，它将运行root命令的PersistentPreRun，但不运行root命令的PersistentPostRun：
import (
"fmt"
"github.com/spf13/cobra"
)
func main(){
var rootCmd = &cobra.Command{
Use: "root",
PersistentPreRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[root] PersistentPreRun with args: %v n", args)
},
PreRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[root] PreRun with args: %v n", args)
},
Run: func(cmd *cobra.Command, args []string) {
fmt.Printf("[root] Run with args: %v n", args)
},
PostRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[root] PostRun with args: %v n", args)
},
PersistentPostRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[root] PersistentPostRun with args: %v n", args)
},
}
var subCmd = &cobra.Command{
Use: "sub",
PreRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[sub] PreRun with args: %v n", args)
},
Run: func(cmd *cobra.Command, args []string) {
fmt.Printf("[sub] Run with args: %v n", args)
},
PostRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[sub] PostRun with args: %v n", args)
},
PersistentPostRun: func(cmd *cobra.Command, args []string) {
fmt.Printf("[sub] PersistentPostRun with args: %v n", args)
},
}
rootCmd.AddCommand(subCmd)
rootCmd.SetArgs([]string{""})
rootCmd.Execute()
fmt.Println()
rootCmd.SetArgs([]string{"sub", "arg1", "arg2",})
rootCmd.Execute()
}
运行结果：
[root] PersistentPreRun with args: []
[root] PreRun with args: []
[root] Run with args: []
[root] PostRun with args: []
[root] PersistentPostRun with args: []
[root] PersistentPreRun with args: [arg1 arg2]
[sub] PreRun with args: [arg1 arg2]
[sub] Run with args: [arg1 arg2]
[sub] PostRun with args: [arg1 arg2]
[sub] PersistentPostRun with args: [arg1 arg2]Golang: Cobra命令行参数库的使用【博客园】
golang命令行库Cobra的使用【简书】
Cobra Generator
https://golang.org/pkg/flag/
https://godoc.org/github.com/spf13/cobra#Command
https://github.com/spf13/pflag
https://godoc.org/github.com/spf13/cobra
github.com/spf13/cobra go cobra包介绍
golang命令行库cobra使用【博客园】
想知道更多？扫描下面的二维码关注我
相关推荐：
加技术群入口（备注：技术）：>>>Learn More<<
免费资料入口（备注：1024）：>>>Learn More<<
免费星球入口：>>>Free<<<
如果觉得我的文章对您有用，请随意打赏。你的支持将鼓励我继续创作！
