Go Cli 工具库：Cobra 框架

Cobra 框架：强大的 Go 命令行工具库

Cobra 是一个用 Go 语言开发的库，用于创建功能强大的现代命令行界面 (CLI) 应用程序。它是一个应用生成器和命令行解析器，可以帮助你快速构建复杂的 CLI 工具，支持子命令、嵌套命令、标志（flags）以及参数验证等功能。许多知名的 Go 项目，如 Kubernetes、Hugo 和 Docker，都使用了 Cobra。

为什么选择 Cobra？

  • 易于使用： 提供简洁的 API，让定义命令、子命令和标志变得非常直观。
  • 功能丰富： 支持多种命令行功能，如别名、自动补全、帮助信息生成等。
  • 结构化： 鼓励通过命令和子命令的层级结构来组织应用程序，使代码更易于管理。
  • 自动生成： 可以自动生成应用程序的骨架代码和命令的帮助信息。
  • 社区活跃： 作为 Go 语言中广泛使用的 CLI 框架，拥有活跃的社区支持和丰富的文档。

基本概念

在深入了解用法之前，我们先理解 Cobra 的几个核心概念：

  • Command： Cobra 的核心，代表一个命令或子命令。每个命令都有名称、描述、短语（用法字符串）以及一个执行函数 (Run)。
  • Args： 命令的非标志参数。Cobra 提供了多种参数验证器。
  • Flags： 命令的选项，通常以 -- 或 - 开头。Cobra 支持持久标志（persistent flags）和本地标志（local flags）。
    • 持久标志： 对当前命令及其所有子命令都可用。
    • 本地标志： 只对当前命令可用。
  • Run： Command 结构体中的一个函数字段，当命令被执行时，该函数会被调用。
  • PreRun/PostRun： 在 Run 函数之前/之后执行的钩子函数。
  • PersistentPreRun/PersistentPostRun： 对于持久钩子，它们会在当前命令及其所有子命令的 PreRun/PostRun 之前/之后执行。

安装 Cobra

Cobra 是一个 Go 模块，你可以通过 Go 命令轻松安装它：

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

Cobra CLI 工具（cobra-cli）也可以帮助你快速生成项目骨架：

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

快速开始：创建一个简单的 CLI 应用

我们将创建一个简单的 greeter 应用，它有一个 hello 命令，可以带一个名字参数。

1. 初始化项目

首先，创建一个新的 Go 模块：

1
2
3
mkdir greeter-app
cd greeter-app
go mod init greeter-app

2. 使用 cobra-cli 初始化 Cobra 项目

如果你已经安装了 cobra-cli，可以这样初始化：

1
cobra-cli init

这会在你的项目目录下生成 main.go 和 cmd/root.go 文件。

  • main.go：应用程序的入口点。
  • cmd/root.go：定义了应用程序的根命令。

3. 定义根命令 (cmd/root.go)

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
package cmd

import (
	"fmt"
	"os"

	"github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
	Use:   "greeter",
	Short: "一个简单的问候应用",
	Long: `greeter 是一个演示 Cobra 用法的简单 CLI 应用。
它能向你问好。`,
	Run: func(cmd *cobra.Command, args []string) {
		// 默认运行逻辑，如果没有任何子命令被指定
		fmt.Println("使用 'greeter --help' 查看可用命令。")
	},
}

// 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.Fprintf(os.Stderr, "Error: %s\n", err)
		os.Exit(1)
	}
}

func init() {
	// 这里可以定义全局标志或持久标志
	// rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.greeter.yaml)")
	// rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}

4. 添加子命令 (hello 命令)

使用 cobra-cli 添加一个 hello 子命令：

1
cobra-cli add hello

这会在 cmd 目录下生成 cmd/hello.go 文件。修改 cmd/hello.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
package cmd

import (
	"fmt"
	"strings"

	"github.com/spf13/cobra"
)

var name string // 用于存储 --name 标志的值

// helloCmd represents the hello command
var helloCmd = &cobra.Command{
	Use:   "hello [name]",
	Short: "向某人问好",
	Long: `使用 hello 命令可以向指定的人问好。
如果没有提供名字，它会问候“世界”。`,
	Args: cobra.MaximumNArgs(1), // 允许最多一个非标志参数
	Run: func(cmd *cobra.Command, args []string) {
		if name != "" {
			// 如果通过 --name 提供了名字
			fmt.Printf("你好, %s!\n", name)
		} else if len(args) > 0 {
			// 如果通过参数提供了名字
			fmt.Printf("你好, %s!\n", strings.Join(args, " "))
		} else {
			// 默认问候
			fmt.Println("你好, 世界!")
		}
	},
}

func init() {
	rootCmd.AddCommand(helloCmd)

	// 定义一个本地标志 --name 或 -n
	helloCmd.Flags().StringVarP(&name, "name", "n", "", "要问候的名字")
}

注意：

  • rootCmd.AddCommand(helloCmd) 将 helloCmd 添加为 rootCmd 的子命令。
  • helloCmd.Flags().StringVarP(...) 定义了一个本地字符串标志 name，它可以是 --name 或 -n。"" 是默认值。

5. 构建并运行

现在，你可以构建并运行你的应用了：

1
2
3
4
5
6
7
go build -o greeter .
./greeter
./greeter hello
./greeter hello Alice
./greeter hello --name Bob
./greeter hello -n Charlie
./greeter hello --help

输出示例：

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
$ ./greeter
使用 'greeter --help' 查看可用命令。

$ ./greeter hello
你好, 世界!

$ ./greeter hello Alice
你好, Alice!

$ ./greeter hello --name Bob
你好, Bob!

$ ./greeter hello -n Charlie
你好, Charlie!

$ ./greeter hello --help
使用方法:
  greeter hello [name] [flags]

别名:
  hello, hi

短语:
  向某人问好

长语:
  使用 hello 命令可以向指定的人问好。
如果没有提供名字，它会问候“世界”。

标志:
  -n, --name string   要问候的名字
  -h, --help          hello 命令的帮助

全局标志:
  --toggle   Help message for toggle

高级用法

持久标志 (Persistent Flags)

持久标志对命令本身及其所有子命令都可用。在 init() 函数中，使用 cmd.PersistentFlags() 定义。

1
2
3
4
5
6
7
8
9
10
// cmd/root.go 中的 init() 函数
func init() {
	// 定义一个持久标志，所有子命令都可以访问
	rootCmd.PersistentFlags().StringP("author", "a", "你的名字", "作者姓名")
}

// 在任何子命令中都可以通过 cmd.Flags().GetString("author") 获取其值
// 例如在 helloCmd 的 Run 函数中
// author, _ := cmd.Flags().GetString("author")
// fmt.Printf("此消息来自 %s\n", author)

标志类型

Cobra 支持多种标志类型：

  • StringVar/StringVarP：字符串
  • BoolVar/BoolVarP：布尔
  • IntVar/IntVarP：整数
  • StringArrayVarP/IntArrayVarP：字符串/整数数组
  • StringSliceVarP/IntSliceVarP：字符串/整数切片
  • 等等…

P 后缀表示可以同时指定长名称和短名称（例如 --name 和 -n）。

参数验证 (Args Validation)

cobra.Command 的 Args 字段允许你定义参数的验证规则：

  • cobra.NoArgs：不允许任何非标志参数。
  • cobra.ArbitraryArgs：允许任意数量的非标志参数。
  • cobra.ExactArgs(n)：只允许精确 n 个非标志参数。
  • cobra.MinimumNArgs(n)：允许至少 n 个非标志参数。
  • cobra.MaximumNArgs(n)：允许最多 n 个非标志参数。
  • cobra.RangeArgs(min, max)：允许 min 到 max 个非标志参数。
  • 自定义函数：你可以定义自己的验证函数。
1
2
3
4
5
6
7
8
// 示例：要求至少一个参数
var myCmd = &cobra.Command{
    Use: "mycommand [arg...]",
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("参数:", args)
    },
}

别名 (Aliases)

为命令添加别名，用户可以使用更短或不同的名称来执行命令：

1
2
3
4
5
var helloCmd = &cobra.Command{
	Use:     "hello",
	Aliases: []string{"hi", "greet"}, // 添加别名
	// ...
}

现在，./greeter hi 和 ./greeter greet 也能执行 hello 命令。

钩子 (Hooks)

Cobra 提供了 PreRun, PostRun, PersistentPreRun, PersistentPostRun 等钩子函数，可以在命令执行前后执行特定逻辑。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
var myCmd = &cobra.Command{
    // ...
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("这是在任何子命令之前运行的持久预运行钩子。")
    },
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("这是在当前命令之前运行的预运行钩子。")
    },
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("这是命令的实际运行逻辑。")
    },
    PostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("这是在当前命令之后运行的后运行钩子。")
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("这是在任何子命令之后运行的持久后运行钩子。")
    },
}

钩子的执行顺序：

  1. PersistentPreRun (根命令)
  2. PersistentPreRun (子命令，如果存在)
  3. PreRun (当前命令)
  4. Run (当前命令)
  5. PostRun (当前命令)
  6. PersistentPostRun (子命令，如果存在)
  7. PersistentPostRun (根命令)

自定义帮助信息

Cobra 会自动生成帮助信息，但你也可以自定义它们：

  • cmd.SetUsageTemplate(template)
  • cmd.SetHelpTemplate(template)
  • cmd.SetVersionTemplate(template)

这允许你完全控制帮助信息的格式。

自动补全 (Autocompletion)

Cobra 可以生成 shell 自动补全脚本，极大地提升用户体验。

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
// 在根命令的 init() 函数中添加一个 'completion' 子命令
var completionCmd = &cobra.Command{
	Use:   "completion [bash|zsh|fish|powershell]",
	Short: "为指定的 shell 生成自动补全脚本",
	Long: `为 Cobra 应用程序生成 shell 自动补全脚本。

要加载 bash 补全到你的当前 shell 会话中：

  source <(greeter completion bash)

要在每次启动 shell 时加载补全，你需要将此行添加到你的 ~/.bashrc 文件中。
`,
	DisableFlagsInUseLine: true,
	ValidArgs:             []string{"bash", "zsh", "fish", "powershell"},
	Args:                  cobra.ExactValidArgs(1),
	Run: func(cmd *cobra.Command, args []string) {
		switch args[0] {
		case "bash":
			cmd.Root().GenBashCompletion(os.Stdout)
		case "zsh":
			cmd.Root().GenZshCompletion(os.Stdout)
		case "fish":
			cmd.Root().GenFishCompletion(os.Stdout, true)
		case "powershell":
			cmd.Root().GenPowerShellCompletion(os.Stdout)
		}
	},
}

func init() {
	rootCmd.AddCommand(completionCmd)
}

现在，用户可以运行 ./greeter completion bash 来生成 bash 补全脚本。

总结

Cobra 是一个非常强大且灵活的 Go 语言命令行框架。通过其清晰的命令结构、丰富的标志管理以及便捷的参数验证，你可以轻松构建出专业级的 CLI 应用程序。熟悉 Cobra 的基本概念和高级特性，将极大地提高你在 Go 中开发命令行工具的效率。详细用法可以参考官网资料