go命令行库-cobra

Cobra介绍

Cobra 是一个用于创建强大的现代 CLI 应用程序的库。几乎包含了你所需要的所有元素。

Cobra 用于许多 Go 项目，例如Kubernetes、Docker、GitHub CLI、Hugo等等。

Cobra提供：

• 简单的基于子命令的 CLI：app server、app fetch等。
• 完全符合 POSIX 的标志（包括短版和长版）
• 嵌套子命令
• 全局、本地和级联标志
• 明智的建议（app srver…你的意思是app server？）
• 命令和标志的自动帮助生成
• 子命令的分组帮助
• -h,–help等的自动帮助标志识别
• 为您的应用程序自动生成 shell 自动补全的功能（bash、zsh、fish、powershell）
• 为您的应用程序自动生成的手册页（man page）
• 命令别名，这样您就可以在不破坏它们的情况下进行更改
• 定义您自己的帮助、使用等的灵活性。
• 可选与viper无缝集成，用于 12 要素应用程序（viper是作者的另一个项目，用来给go语言程序提供配置解决方案，可以将cobra和viper结合使用）

Cobra安装

cobra提供了用于go get安装的最新版本的库。

代码语言：javascript复制

go get -u github.com/spf13/cobra@latest

同时，Cobra提供了一个方便的命令行程序生成器cobra-cli，后续我们会使用cobra-cli来自动生成模板，简化我们的工作。因此也需要安装它。

代码语言：javascript复制

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

需要注意的是，Go 会自动将cobra-cli安装在你的GOPATH/bin目录中，因此你要确保GOPATH/bin被你添加到了环境变量中。否则你无法使用cobra-cli程序。以Debian系统为例，你可以通过go env|grep GOPATH命令来查看你的GOPATH，然后将GOPATH/bin添加到~/.bashrc文件中，例如：

代码语言：javascript复制

export PATH=$PATH:/home/zy/go/bin

在~/.bashrc中添加上面这行之后，执行下面的命令，使其生效。

代码语言：javascript复制

source ~/.bashrc

Cobra使用

Cobra提供了一个生成器（cobra-cli），可以用来初始化你的命令行程序。这是将 Cobra 整合到您的应用程序中的最简单方法。当然你也可以手动来创建自己的命令行程序。cobra-cli只是帮助你简化了创建过程。下面使用cobra-cli生成器来创建我们自己的命令行程序。

创建一个新目录并初始化go mod

mkdir mycmd cd mycmd go mod init mycmd

使用cobra-cli来初始化一个项目

确保你以及按照安装步骤安装了cobra以及cobra-cli，并将cobra-cli添加到了环境变量中。在mycmd目录下执行下面的命令。

代码语言：javascript复制

 cobra-cli init

执行该命令会在当前目录下生成cmd目录，main.go等文件。现在尝试运行一下自动生成的命令行程序。

代码语言：javascript复制

 go run main.go

确保可以成功运行即可

修改自动生成的程序为你自己的功能

使用cobra-cli生成以后，目录结构如下所示。

代码语言：javascript复制

 .
 ├── cmd
 │   └── root.go
 ├── go.mod
 ├── go.sum
 ├── LICENSE
 └── main.go

我们来看一下自动生成的文件中的内容。由于我们在自动生成的时候，没有使用-l(–license)参数，因此自动生成的LICENSE文件为空。main.go文件和cmd目录下的root.go才是我们关心的重点。

代码语言：javascript复制

// main.go
package main

import "mycmd/cmd"

func main() {
    cmd.Execute()
}

main.go文件非常简单，就只是简单的初始化cobra。让我们再来看看root.go文件。

代码语言：javascript复制

// root.go
package cmd

import (
    "os"

    "github.com/spf13/cobra"
)

// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
    Use:   "mycmd",
    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() {
    err := rootCmd.Execute()
    if err != nil {
        os.Exit(1)
    }
}

func init() {
    // 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/.mycmd.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")
}

首先是定义一个cobra.Command指针类型的变量rootCmd，其中定义了Use，Short, Long字段的值，关于这些字段的含义，可以通过查看Command结构体的注释来了解。另外就是在init函数中，给rootCmd添加了一个标志toggle。Execute()函数就是我们在main.go文件中调用的函数。现在，我们来修改一下root.go程序。让其展示我们的功能。

代码语言：javascript复制

// 修改后的root.go
package cmd

import (
    "os"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "test",
    Short: "A test programming",
    Long:  "A test programming",

    Run: func(cmd *cobra.Command, args []string) {
        cmd.Help() // 当不带有任何参数或者标志执行程序的时候，输出help
    },
}

func Execute() {
    err := rootCmd.Execute()
    if err != nil {
        os.Exit(1)
    }
}

func init() {
    rootCmd.CompletionOptions.DisableDefaultCmd = true // 禁用Completion命令
    rootCmd.Version = "0.0.1"                         // 设置version
}

执行main.go，输出如下所示：

代码语言：javascript复制

 A test programming

 Usage:
 test [flags]

 Flags:
 -h, --help      help for test
 -v, --version   version for test

我们加上标志-v(go run main.go -v)再来执行一次，输出如下：

代码语言：javascript复制

 test version 0.0.1

我们通过rootCmd.CompletionOptions.DisableDefaultCmd = true这行代码禁用掉了completion命令。它可以提供生成shell completion，来给予命令补全等功能。详细的文档可以查看Generating shell completions

增加新命令

初始化 cobra 应用程序后，你可以继续使用cobra-cli向应用程序添加其他命令。执行此操作的命令是cobra-cli add [command]，例如：

代码语言：javascript复制

 cobra-cli add start

执行该命令之后，你会发现在cmd目录下生成了一个名为start.go的文件，内容如下所示：

代码语言：javascript复制

// start.go
package cmd

import (
    "fmt"

    "github.com/spf13/cobra"
)

// startCmd represents the start command
var startCmd = &cobra.Command{
    Use:   "start",
    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("start called")
    },
}

func init() {
    rootCmd.AddCommand(startCmd)

    // Here you will define your flags and configuration settings.

    // Cobra supports Persistent Flags which will work for this command
    // and all subcommands, e.g.:
    // startCmd.PersistentFlags().String("foo", "", "A help for foo")

    // Cobra supports local flags which will only run when this command
    // is called directly, e.g.:
    // startCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}

这段代码也很容易理解，startCmd这个结构体指针中配置了结构体中的一些参数；init函数中rootCmd.AddCommand(startCmd)这行代码将startCmd作为一个命令添加到rootCmd中。此时默认的父级就是rootCmd。还可以使用-p标志直接指定父命令。例如:

代码语言：javascript复制

 cobra-cli add time -p "startCmd"

需要注意的是：“指定父级时，请确保与代码中使用的变量名匹配”。这样生成的time.go文件如下所示：

代码语言：javascript复制

// time.go
package cmd

import (
    "fmt"

    "github.com/spf13/cobra"
)

// timeCmd represents the time command
var timeCmd = &cobra.Command{
    Use:   "time",
    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("time called")
    },
}

func init() {
    startCmd.AddCommand(timeCmd)

    // Here you will define your flags and configuration settings.

    // Cobra supports Persistent Flags which will work for this command
    // and all subcommands, e.g.:
    // timeCmd.PersistentFlags().String("foo", "", "A help for foo")

    // Cobra supports local flags which will only run when this command
    // is called directly, e.g.:
    // timeCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}

可以看到init函数中是把timeCmd添加到startCmd，而不是之前的start命令，会把startCmd添加到rootCmd。这样，我们可以这样执行命令。

代码语言：javascript复制

 go run main.go start time

还有一点需要注意，那就是命令的命令需要遵循驼峰命名法。

编辑 cmd 中的文件并为您的应用程序自定义它们 在第三步的时候，我们已经介绍过了简单的方式来自定义它们。下面对command中常用的参数做一个说明。

参数	含义
Use	显示用法，例如：add [-F file
Short	是help中输出的简短描述
Long	是help中输出的长描述
Example	如何使用该命令的示例
Aliases	别名数组，用来给命令起别名
GroupID	该子命令在其父命令的help标志输出中分组时使用的组id
Arg	参数
Version	版本标志。如果该值非空，并且命令没有定义Version标志，则Version标志将被添加到命令中，如果定义了Version标志，将打印Version变量的内容。如果命令没有定义一个简写的“v”标志，也将添加简写的“v”标志。
Run	通常是实际的功函数，即使用该命令的时候会调用的函数。函数原型func(cmd *Command, args []string)
RunE	和Run类似，只不过会返回一个error，函数原型func(cmd *Command, args []string) error

使用标志

由于标志是在不同的位置定义和使用的，我们需要在外部定义一个具有正确范围的变量来分配标志以使用。例如：

代码语言：javascript复制

var Verbose bool
var Source string

分配标志有两种不同的方法。

持久标志

标志可以是“持久的”，这意味着该标志将可用于分配给它的命令以及该命令下的每个命令。对于全局标志，将标志分配为根上的持久标志。

代码语言：javascript复制

rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")

本地标志

也可以在本地分配一个标志，该标志仅适用于该特定命令。

代码语言：javascript复制

localCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")

父命令上的本地标志

默认情况下，Cobra 仅解析目标命令上的本地标志，而忽略父命令上的任何本地标志。通过启用Command.TraverseChildren，Cobra 将在执行目标命令之前解析每个命令上的本地标志。

代码语言：javascript复制

command := cobra.Command{
Use: "print [OPTIONS] [COMMANDS]",
TraverseChildren: true,
}

必需的标志

默认情况下，标志是可选的。相反，如果您希望您的命令在未设置标志时报告错误，请将其标记为必需：

代码语言：javascript复制

rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkFlagRequired("region")

或者，对于持久标志：

代码语言：javascript复制

rootCmd.PersistentFlags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkPersistentFlagRequired("region")

标记组

如果您有不同的标志必须一起提供（例如，如果他们提供–username标志，他们也必须提供–password标志），那么 Cobra 可以强制执行该要求：

代码语言：javascript复制

rootCmd.Flags().StringVarP(&u, "username", "u", "", "Username (required if password is set)")
rootCmd.Flags().StringVarP(&pw, "password", "p", "", "Password (required if username is set)")
rootCmd.MarkFlagsRequiredTogether("username", "password")

如果它们表示互斥选项，例如将输出格式指定为其中一个–json或–yaml但从不同时指定，您还可以防止同时提供不同的标志：

代码语言：javascript复制

rootCmd.Flags().BoolVar(&u, "json", false, "Output in JSON")
rootCmd.Flags().BoolVar(&pw, "yaml", false, "Output in YAML")
rootCmd.MarkFlagsMutuallyExclusive("json", "yaml")

位置和自定义参数

可以使用Args字段来指定位置参数的验证Command。内置以下验证器：

• 参数数量：
  • NoArgs- 如果有任何位置参数，则报告错误。
  • ArbitraryArgs- 接受任意数量的参数。
  • MinimumNArgs(int)- 如果提供的位置参数少于 N 个，则报告错误。
  • MaximumNArgs(int)- 如果提供的位置参数超过 N 个，则报告错误。
  • ExactArgs(int)- 如果不完全有 N 个位置参数，则报告错误。
  • RangeArgs(min, max)min- 如果 args 的数量不在 和 之间，则报告错误max。
• 参数内容： 如果在OnlyValidArgsValidArgs字段中未指定任何位置参数，则报告错误Command，可以选择将其设置为位置参数的有效值列表。如果Args未定义或nil，则默认为ArbitraryArgs。

此外，MatchAll(pargs …PositionalArgs)可以将现有检查与任意其他检查相结合。例如，如果你想在不完全有 N 个位置参数的情况下报告错误，或者如果有任何位置参数不在 的ValidArgs字段中Command，你可以调用and MatchAll，如下所示：ExactArgsOnlyValidArgs

代码语言：javascript复制

var cmd = &cobra.Command{
  Short: "hello",
  Args: cobra.MatchAll(cobra.ExactArgs(2), cobra.OnlyValidArgs),
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hello, World!")
  },
}

另外，你可以设置任何满足func(cmd *cobra.Command, args []string) error. 例如：

代码语言：javascript复制

var cmd = &cobra.Command{
  Short: "hello",
  Args: func(cmd *cobra.Command, args []string) error {
    // Optionally run one of the validators provided by cobra
    if err := cobra.MinimumNArgs(1)(cmd, args); err != nil {
        return err
    }
    // Run the custom validation logic
    if myapp.IsValidColor(args[0]) {
      return nil
    }
    return fmt.Errorf("invalid color specified: %s", args[0])
  },
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hello, World!")
  },
}

关于cobra库的更多使用指南，请参考该项目的官方文档

参考资料

• https://github.com/spf13/cobra/blob/main/README.md

命令行工具

0 人点赞