投稿
  1. 云图网首页
  2. 技术专区
  3. 编程笔记

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是建立在结构的命令、参数和标志之上。命令（Commands）代表操作，参数（Args）和标志（Flags）是这些行动的修饰符。

APPNAME COMMAND ARG --FLAG

cobra使用

1.安装cobra

首先，使用go get安装最新版本

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

安装成功之后会生成一个名为cobra的可执行文件：

[email protected]:~$ ls -al $GOPATH/bin | grep cobra

2.简单使用，demo

使用Cobra生成应用程序

假设现在我们要开发一个基于CLI的命令程序，名字为demo。执行如下命令：

[email protected]:~$ cd $GOPATH/src/github.com/spf13/ 
[email protected]:~/go/src/github.com/spf13$ cobra init demo --pkg-name=github.com/spf13/demo 
Your Cobra applicaton is ready at 
/home/xxx/go/src/github.com/spf13/demo 
 
[email protected]:~/go/src/github.com/spf13$ cd demo/

在$GOPATH/src/github.com/spf13目录下会生成一个demo的文件夹，结构如下：

[email protected]:~/go/src/github.com/spf13/demo$ tree 
. 
├── cmd 
│   └── root.go 
├── LICENSE 
└── main.go 
 
1 directory, 3 files

测试cobra效果：

[email protected]:~/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并使用以下内容填充它：

[email protected]:~/go/src/github.com/spf13/demo$ cobra add version 
version created at /home/zhuzhonghua/go/src/github.com/spf13/demo

此目录结构变更为：

[email protected]:~/go/src/github.com/spf13/demo$ tree 
. 
├── cmd 
│   ├── root.go 
│   └── version.go 
├── LICENSE 
└── main.go 
 
1 directory, 4 files

现在我们来执行以下这个子命令：

[email protected]:~/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文件，项目文件结构为：

[email protected]:~/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命令之后，结果为：

xxx:demo xxx$ go run main.go version help 
Here is the help information

3.使用Flags

Flags提供了修饰符来控制动作命令的操作。

Persistent Flags：全局性flag, 可用于它所分配的命令以及该命令下的每个命令。在根上分配标志作为全局flag。

Local Flags：局部性flag,在本args分配一个标志，该标志仅适用于该特定命令。

Required flags：必选flag，flag默认是可选的。如果希望命令在未设置flag时报告错误，请将其标记为required。

添加Flags

如果仔细看过上面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时报告错误，请将其标记为必需

获取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 %s/n", str)

运行命令go run main.go version -f vvvv，获得结果如下：

The param vale is vvvv 
Version 1.0.0 for demo

使用Args

可以使用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函数）：

import ( 
    "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）：

xxx: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。

我们再来试一下添加参数的结果：

xxx:demo hidden$ go run main.go args 1 
args called, args:  [1] 
xxx:demo hidden$ go run main.go args 1 2 3 4 
args called, args:  [1 2 3 4]

示例中的Args函数可以替换为

Args: cobra.MinimumNArgs(1),

读者可以自行验证一下效果。

Help命令

前面的示例中出现了cmd/help.go，为了不产生迷惑，我们把这个文件先删除掉。

当您有子命令时，Cobra会自动为您的应用程序添加一个帮助命令。当用户运行“app help”时会调用此方法。此外，帮助还将支持所有其他命令作为输入。比如说，你有一个名为’create’的命令，没有任何额外的配置; 当’app help create’被调用时，Cobra会工作。每个命令都会自动添加’ – help’标志。

可以在终端输入cobra或者cobra help命令看一下实际的效果:

[email protected]:~$ 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命令或自定义的模板，通过以下函数实现：

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

后两者也适用于子命令。

Usage

当用户提供无效标志或无效命令时，Cobra会通过向用户显示“usage”来做出响应。

示例：

[email protected]:~$ 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.

自定义Usage

您可以提供自己的使用功能或模板供Cobra使用。与Help一样，函数和模板可以通过公共方法覆盖：

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

PreRun 和 PostRun钩子

我们可以在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命令 
[root] PersistentPreRun with args: [] 
[root] PreRun with args: [] 
[root] Run with args: [] 
[root] PostRun with args: [] 
[root] PersistentPostRun with args: [] 
 
 
//执行sub子命令 
[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使用【博客园】 
 
微信公众号：朱小厮的博客

原创文章，作者：ItWorker，如若转载，请注明出处：https://blog.ytso.com/tech/pnotes/18128.html

赞 (0)
0 0
上一篇 2021年7月19日 20:50
下一篇 2021年7月19日 20:50

相关推荐

发表回复

登录后才能评论