Cobra - 一个 Golang 命令行项目生成工具

Author Avatar
Jsharkc 7月 17, 2017

Cobra - Golang 命令行库

简介:

Cobra 是一个创建 CLI 命令行的 golang 库。

组成:

Cobra 结构由三部分组成:命令( Command )、参数( Args )、标志( Flag )。

1
2
3
4
5
6
type Command struct {
Use string // The one-line usage message.
Short string // The short description shown in the 'help' output.
Long string // The long message shown in the 'help<this-command>' output.
Run func(cmd *Command, args []string) // Run runs the command.
}

前三个是不同场景下的说明,最后一个是要执行的函数。

安装

安装 Cobra 很简单,首先,用 go get 安装最新版本的库,这个命令会安装 Cobra 框架生成工具和依赖。

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

然后,把 Cobra 添加到你的 app 中:

1
import "github.com/spf13/cobra"

快速开始

​一般用 cobra 命令生成d的项目结构如下:

1
2
3
4
5
6
7
▾ appName/
▾ cmd/
add.go
your.go
commands.go
here.go
main.go

main 函数中非常简洁,只有一个目的:初始化 Cobra.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package main

import (
"fmt"
"os"

"{pathToYourApp}/cmd"
)

func main() {
if err := cmd.RootCmd.Execute(); err != nil {
fmt.Println(err)
os.Exit(1)
}
}

用 Cobra 工具生成项目框架

cobra init

cobra init [yourAppName] ,这个命令可以让你的程序有一个正确的结构,你立刻能够感受到 Cobra 带给你的快乐,你可以配置它自动生成你需要的开源协议。

1
cobra init newAppName

newAppName 是你的项目名称。它会在你的 GOPATH 目录下面生成项目。

我们看一下 main.go 函数

1
2
3
4
5
6
7
package main

import "cobra_exp1/cmd"

func main() {
cmd.Execute()
}

main 调用 cmd.Execute(),那我们找到这个地方,cmd/root.go 文件:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
package cmd

import (
"fmt"
"os"

"github.com/spf13/cobra"
"github.com/spf13/viper"
)

var cfgFile string

// RootCmd represents the base command when called without any subcommands
var RootCmd = &cobra.Command{
Use: "cobra_exp1",
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 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/.cobra_exp1.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 != "" { // enable ability to specify config file via flag
viper.SetConfigFile(cfgFile)
}

viper.SetConfigName(".cobra_exp1") // name of config file (without extension)
viper.AddConfigPath("$HOME") // adding home directory as first search path
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())
}
}

我们看到 Execute() 函数中调用 RootCmd.Execute(),RootCmd 是开始讲组成 Command 结构的一个实例。

我们运行看看:

1
2
3
4
5
6
7
> 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.

空空如也,还什么也没有,那接下来我们来添加一些子命令。

cobra add

这个命令用来创建子命令,子命令就是像下面这样:

  • app serve
  • app config
  • app config create

在你项目的目录下,运行下面这些命令:

1
2
3
cobra add serve
cobra add config
cobra add create -p 'configCmd'

这样以后,你就可以运行上面那些 app serve 之类的命令了。项目目录如下:

1
2
3
4
5
6
▾ app/
▾ cmd/
serve.go
config.go
create.go
main.go

然后再运行程序:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
❯ 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.

Usage:
llleon [command]

Available Commands:
config A brief description of your command
help Help about any command
serve A brief description of your command

Flags:
--config string config file (default is $HOME/.llleon.yaml)
-h, --help help for llleon
-t, --toggle Help message for toggle

Use "llleon [command] --help" for more information about a command.

现在我们有了三个子命令,并且都可以使用,然后只要添加命令逻辑就能真正用了。

Flag

cobra 有两种 flag,一个是全局变量,一个是局部变量。全局什么意思呢,就是所以子命令都可以用。局部的只有自己能用。先看全局的:

1
RootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra_exp1.yaml)")

在看局部的:

1
RootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")

区别就在 RootCmd 后面的是 Flags 还是 PersistentFlags。

好了,入门教程到此结束,感兴趣的童鞋可以到 Cobra 深入研究一番。