使用 spf13/cobra 构建强大的 Go 命令行应用

spf13/cobra 是 Go 语言中非常流行的一个库，用于创建命令行应用（CLI）。它提供了一种强大且易于使用的框架来开发支持复杂命令结构的应用程序。Cobra 库主要用于创建像 kubectl、docker 这样的工具。该库的主要功能包括命令管理、标志（flags）管理、自动生成帮助文档、命令别名、子命令管理等

1. 初始化项目

首先，你需要在你的项目中引入 cobra 库。可以通过 go get 命令安装：

go get -u github.com/spf13/cobra

然后，创建一个新的 Go 项目，并初始化 cobra。

go mod init mycli

2. 创建一个基本的 Cobra 应用程序

Cobra 应用的核心是 Command 结构体，该结构体包含了命令的名字、简短描述、详细描述、以及执行命令的具体函数。

我们首先来创建一个最简单的 Cobra 应用，它包含一个根命令（根命令就是 CLI 程序的入口）。

代码结构：

mycli/
|-- cmd/
|   |-- root.go
|-- main.go

main.go 文件：

package main

import (
    "mycli/cmd"
)

func main() {
    cmd.Execute() // 执行命令
}

cmd/root.go 文件：

package cmd

import (
    "fmt"
    "github.com/spf13/cobra"
    "os"
)

var rootCmd = &cobra.Command{
    Use:   "mycli",         // 命令的使用方法，如：mycli
    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:

This is a CLI application built with Cobra.`,
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("Hello from mycli")
    },
}

// Execute 是外部调用的接口，用于执行命令
func Execute() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
}

3. 添加子命令

Cobra 的一个强大之处在于它支持子命令。例如，git 命令有 git clone、git commit 等子命令。我们也可以为我们的 CLI 程序添加子命令。

添加 version 子命令

在 cmd 目录下创建一个新的 version.go 文件：

package cmd

import (
    "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("MyCLI v0.1 -- HEAD")
    },
}

// 初始化函数，将子命令添加到根命令
func init() {
    rootCmd.AddCommand(versionCmd)
}

这样，我们的 mycli 就有了 version 子命令，执行 mycli version 会输出版本信息。

4. 添加标志（Flags）

Cobra 支持为命令添加标志。标志可以是持久的（作用于命令及其所有子命令），也可以是局部的（仅作用于当前命令）。

为根命令添加全局标志

我们可以为根命令添加一个 --verbose 标志，用来控制输出的详细程度。

var verbose bool

func init() {
    // 将 `verbose` 标志添加到根命令，并设置默认值为 false
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Enable verbose output")
}

然后，我们在 Run 函数中使用该标志：

Run: func(cmd *cobra.Command, args []string) {
    if verbose {
        fmt.Println("Verbose mode enabled")
    } else {
        fmt.Println("Hello from mycli")
    }
}

子命令的标志

我们还可以为每个子命令定义局部标志。局部标志只影响该命令。例如，我们可以为 version 命令添加一个 --beta 标志：

var beta bool

func init() {
    versionCmd.Flags().BoolVarP(&beta, "beta", "b", false, "Print the beta version")
}

Run: func(cmd *cobra.Command, args []string) {
    if beta {
        fmt.Println("MyCLI v0.1-beta")
    } else {
        fmt.Println("MyCLI v0.1 -- HEAD")
    }
}

5. 自动生成帮助文档

Cobra 自动为你生成帮助文档。每个命令都会有一个 --help 标志来显示该命令的使用方法。

例如，执行 mycli --help 会显示：

A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:

This is a CLI application built with Cobra.

Usage:
  mycli [flags]
  mycli [command]

Available Commands:
  help        Help about any command
  version     Print the version number of MyCLI

Flags:
  -h, --help     help for mycli
  -v, --verbose  Enable verbose output

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

6. 命令别名（Aliases）

你可以为命令添加别名，使得用户可以通过不同的名字调用同一个命令。例如，我们可以为 version 命令添加一个别名 v：

var versionCmd = &cobra.Command{
    Use:     "version",
    Aliases: []string{"v"},  // 别名
    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("MyCLI v0.1 -- HEAD")
    },
}

现在用户可以通过 mycli v 来执行 version 命令。

7. 错误处理

Cobra 会自动处理命令行解析时的错误。如果用户提供了一个未知命令或参数，Cobra 会显示错误信息。例如，执行 mycli unknown 会输出类似这样的错误：

Error: unknown command "unknown" for "mycli"
Run 'mycli --help' for usage.

你可以通过自定义错误处理函数来自定义这种行为。

8. 完整示例

以下是一个包含多个子命令、标志和错误处理的完整示例：

package main

import (
    "fmt"
    "os"

    "github.com/spf13/cobra"
)

var verbose bool

// 根命令
var rootCmd = &cobra.Command{
    Use:   "mycli",
    Short: "MyCLI is a sample CLI application",
    Run: func(cmd *cobra.Command, args []string) {
        if verbose {
            fmt.Println("Verbose mode enabled")
        } else {
            fmt.Println("Hello from MyCLI")
        }
    },
}

// 版本子命令
var versionCmd = &cobra.Command{
    Use:     "version",
    Aliases: []string{"v"},
    Short:   "Print the version number",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("MyCLI v0.1")
    },
}

func main() {
    // 将标志添加到根命令
    rootCmd.PersistentFlags().BoolVarP(&verbose, "verbose", "v", false, "Enable verbose output")

    // 将版本子命令添加到根命令
    rootCmd.AddCommand(versionCmd)

    // 执行命令
    if err := rootCmd.Execute(); err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
}