go 库 Cobra 现代化的命令行框架

Posted 2022-12-31

tags:

篇首语：本文由小常识网(cha138.com)小编为大家整理，主要介绍了go 库 Cobra 现代化的命令行框架相关的知识，希望对你有一定的参考价值。

go 库 Cobra 现代化的命令行框架

文章目录

go 库 Cobra 现代化的命令行框架

1. 简介
2. 主要功能
3. 应用举例
4. Cobra 安装
5. 使用 Cobra 库创建命令

5.1 创建 rootCmd
5.2 创建 main.go
5.3 添加命令
5.4 编译并运行

6. 特性

6.1 使用标志
6.2 非选项参数验证
6.3 PreRun and PostRun Hooks

7. cobra-cli 命令

7.1 安装
7.2 cobra-cli 初始化
7.3 向项目添加命令

1. 简介

Cobra 既是一个可以创建强大的现代 CLI 应用程序的库，也是一个可以生成应用和命令文件的程序。有许多大型项目都是用 Cobra 来构建应用程序的，例如 Kubernetes、Docker、etcd、Rkt、Hugo 等。

Cobra 建立在 commands、arguments 和 flags 结构之上。

commands 代表命令，
arguments 代表非选项参数，
flags 代表选项参数（也叫标志）。

一个好的应用程序应该是易懂的，用户可以清晰地知道如何去使用这个应用程序。应用程序通常遵循如下模式：APPNAME VERB NOUN --ADJECTIVE或者APPNAME COMMAND ARG --FLAG，例如：

# server是 commands，port 是 flag
$ hugo server --port=1313

# clone 是 commands，URL 是 arguments，brae 是 flag
$ git clone URL --bare # clone 是一个命令，URL是一个非选项参数，bare是一个选项参数


$ docker info --help 
Usage:  docker info [OPTIONS]

Display system-wide information

Options:
  -f, --format string   Format the output using the given Go template

这里，VERB 代表动词，NOUN 代表名词，ADJECTIVE 代表形容词。

Cobra 提供了两种方式来创建命令：Cobra 命令和 Cobra 库。Cobra 命令可以生成一个 Cobra 命令模板，而命令模板也是通过引用 Cobra 库来构建命令的。

2. 主要功能

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
自动识别帮助 flag -h，–help
自动生成应用程序在 bash 下命令自动完成功能
自动生成应用程序的 man 手册
命令行别名
自定义 help 和 usage 信息
可选的与 viper apps 的紧密集成

3. 应用举例

obra 被用于许多 Go 项目中，例如：Kubernetes、Hugo和Github CLI等，更多广泛使用的项目有：

4. Cobra 安装

使用Cobra很简单。首先，使用go get安装最新版本的库。

$ go get -u github.com/spf13/cobra@latest
go: downloading github.com/inconshreveable/mousetrap v1.0.1
go: downloading github.com/inconshreveable/mousetrap v1.1.0
go: added github.com/inconshreveable/mousetrap v1.1.0
go: added github.com/spf13/cobra v1.6.1
go: added github.com/spf13/pflag v1.0.5

接下来 ,导入 Cobra:

import "github.com/spf13/cobra"

5. 使用 Cobra 库创建命令

如果要用 Cobra 库编码实现一个应用程序，需要首先创建一个空的 main.go 文件和一个 rootCmd 文件，之后可以根据需要添加其他命令。具体步骤如下：

5.1 创建 rootCmd

$ mkdir -p newApp2 && cd newApp2

通常情况下，我们会将 rootCmd 放在文件 cmd/root.go 中。

var rootCmd = &cobra.Command
  Use:   "hugo",
  Short: "Hugo is a very fast static site generator",
  Long: `A Fast and Flexible Static Site Generator built with
                love by spf13 and friends in Go.
                Complete documentation is available at http://hugo.spf13.com`,
  Run: func(cmd *cobra.Command, args []string) 
    // Do Stuff Here
  ,


func Execute() 
  if err := rootCmd.Execute(); err != nil 
    fmt.Println(err)
    os.Exit(1)

还可以在 init() 函数中定义标志和处理配置，例如 cmd/root.go。

import (
  "fmt"
  "os"

  homedir "github.com/mitchellh/go-homedir"
  "github.com/spf13/cobra"
  "github.com/spf13/viper"
)

var (
    cfgFile     string
    projectBase string
    userLicense string
)

func init() 
  cobra.OnInitialize(initConfig)
  rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")
  rootCmd.PersistentFlags().StringVarP(&projectBase, "projectbase", "b", "", "base project directory eg. github.com/spf13/")
  rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "Author name for copyright attribution")
  rootCmd.PersistentFlags().StringVarP(&userLicense, "license", "l", "", "Name of license for the project (can provide `licensetext` in config)")
  rootCmd.PersistentFlags().Bool("viper", true, "Use Viper for configuration")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
  viper.BindPFlag("projectbase", rootCmd.PersistentFlags().Lookup("projectbase"))
  viper.BindPFlag("useViper", rootCmd.PersistentFlags().Lookup("viper"))
  viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
  viper.SetDefault("license", "apache")


func initConfig() 
  // Dont forget to read config either from cfgFile or from home directory!
  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 ".cobra" (without extension).
    viper.AddConfigPath(home)
    viper.SetConfigName(".cobra")
  

  if err := viper.ReadInConfig(); err != nil 
    fmt.Println("Cant read config:", err)
    os.Exit(1)

5.2 创建 main.go

我们还需要一个 main 函数来调用 rootCmd，通常我们会创建一个 main.go 文件，在 main.go 中调用 rootCmd.Execute() 来执行命令：

package main

import (
  "newApp2/cmd/cmd"
)

func main() 
  cmd.Execute()

需要注意，main.go 中不建议放很多代码，通常只需要调用 cmd.Execute() 即可。

5.3 添加命令

除了 rootCmd，我们还可以调用 AddCommand 添加其他命令，通常情况下，我们会把其他命令的源码文件放在 cmd/ 目录下，例如，我们添加一个 version 命令，可以创建 cmd/version.go 文件，内容为：

package cmd

import (
  "fmt"

  "github.com/spf13/cobra"
)

func init() 
  rootCmd.AddCommand(versionCmd)


var versionCmd = &cobra.Command
  Use:   "version",
  Short: "Print the version number of Hugo",
  Long:  `All software has versions. This is Hugos`,
  Run: func(cmd *cobra.Command, args []string) 
    fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
  ,

本示例中，我们通过调用rootCmd.AddCommand(versionCmd)给 rootCmd 命令添加了一个 versionCmd 命令。

5.4 编译并运行

创建.cobra.yaml文件

$ cat  /c/Users/XH/.cobra.yaml
author: Steve Francia <spf@spf13.com>
license: MIT
useViper: true

将 main.go 中pathToYourApp替换为对应的路径，例如本示例中 pathToYourApp 为github.com/marmotedu/gopractise-demo/cobra/newApp2

$ cd /d/goprojects/src/github.com/marmotedu/gopractise-demo/cobra/newApp2
$ go mod init newApp2
$ go build -v .
$ ./newApp2 -h
A Fast and Flexible Static Site Generator built with
love by spf13 and friends in Go.
Complete documentation is available at http://hugo.spf13.com
 
Usage:
hugo [flags]
hugo [command]
 
Available Commands:
help Help about any command
version Print the version number of Hugo
 
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 hugo
-l, --license licensetext Name of license for the project (can provide licensetext in config)
-b, --projectbase string base project directory eg. github.com/spf13/
--viper Use Viper for configuration (default true)
 
Use "hugo [command] --help" for more information about a command.


$ $ ./newApp2.exe version
Hugo Static Site Generator v0.9 -- HEAD

6. 特性

6.1 使用标志

Cobra 可以跟 Pflag 结合使用，实现强大的标志功能。使用步骤如下：

使用持久化的标志
标志可以是“持久的”，这意味着该标志可用于它所分配的命令以及该命令下的每个子命令。可以在 rootCmd 上定义持久标志：

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

使用本地标志
也可以分配一个本地标志，本地标志只能在它所绑定的命令上使用：

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

--source标志只能在 rootCmd 上引用，而不能在 rootCmd 的子命令上引用。

将标志绑定到 Viper
我们可以将标志绑定到 Viper，这样就可以使用 viper.Get() 获取标志的值。

var author string

func init() 
  rootCmd.PersistentFlags().StringVar(&author, "author", "YOUR NAME", "Author name for copyright attribution")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))

设置标志为必选
默认情况下，标志是可选的，我们也可以设置标志为必选，当设置标志为必选，但是没有提供标志时，Cobra 会报错。

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

6.2 非选项参数验证

在命令的过程中，经常会传入非选项参数，并且需要对这些非选项参数进行验证，Cobra 提供了机制来对非选项参数进行验证。可以使用 Command 的 Args 字段来验证非选项参数。Cobra 也内置了一些验证函数：

NoArgs：如果存在任何非选项参数，该命令将报错。
ArbitraryArgs：该命令将接受任何非选项参数。
OnlyValidArgs：如果有任何非选项参数不在 Command 的 ValidArgs 字段中，该命令将报错。
MinimumNArgs(int)：如果没有至少 N 个非选项参数，该命令将报错。
MaximumNArgs(int)：如果有多于 N 个非选项参数，该命令将报错。
ExactArgs(int)：如果非选项参数个数不为 N，该命令将报错。
ExactValidArgs(int)：如果非选项参数的个数不为 N，或者非选项参数不在 Command 的 ValidArgs 字段中，该命令将报错。
RangeArgs(min, max)：如果非选项参数的个数不在 min 和 max 之间，该命令将报错。

使用预定义验证函数，示例如下：

var cmd = &cobra.Command
  Short: "hello",
  Args: cobra.MinimumNArgs(1), // 使用内置的验证函数
  Run: func(cmd *cobra.Command, args []string) 
    fmt.Println("Hello, World!")
  ,

当然你也可以自定义验证函数，示例如下：

var cmd = &cobra.Command
  Short: "hello",
  // Args: cobra.MinimumNArgs(10), // 使用内置的验证函数
  Args: func(cmd *cobra.Command, args []string) error  // 自定义验证函数
    if len(args) < 1 
      return errors.New("requires at least one arg")
    
    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!")
  ,

6.3 PreRun and PostRun Hooks

在运行 Run 函数时，我们可以运行一些钩子函数，比如 PersistentPreRun 和 PreRun 函数在 Run 函数之前执行，PersistentPostRun 和 PostRun 在 Run 函数之后执行。如果子命令没有指定PersistentRun函数，则子命令将会继承父命令的PersistentRun函数。这些函数的运行顺序如下：

PersistentPreRun
PreRun
Run
PostRun
PersistentPostRun

注意，父级的 PreRun 只会在父级命令运行时调用，子命令是不会调用的。

Cobra 还支持很多其他有用的特性，比如：

自定义 Help 命令；
可以自动添加--version标志，输出程序版本信息；
当用户提供无效标志或无效命令时，Cobra 可以打印出 usage 信息；
当我们输入的命令有误时，Cobra 会根据注册的命令，推算出可能的命令，等等。

7. cobra-cli 命令

7.1 安装

cobra-cli是一个命令行程序，用于生成cobra应用程序和命令文件。它将引导您的应用程序脚手架，以快速开发基于cobra的应用程序。这是将Cobra合并到应用程序中最简单的方法。

可以通过以下命令安装:

$ go install github.com/spf13/cobra-cli@latest
go: downloading github.com/spf13/cobra-cli v1.3.0
go: downloading github.com/spf13/cobra v1.3.0
go: downloading github.com/spf13/viper v1.10.1
go: downloading github.com/fsnotify/fsnotify v1.5.1
go: downloading github.com/mitchellh/mapstructure v1.4.3
go: downloading github.com/magiconair/properties v1.8.5
go: downloading github.com/spf13/afero v1.6.0
go: downloading github.com/spf13/cast v1.4.1
go: downloading gopkg.in/ini.v1 v1.66.2
go: downloading github.com/pelletier/go-toml v1.9.4
go: downloading golang.org/x/text v0.3.7

cobra-cli命令自动将它安装在你的$GOPATH/bin目录中

$ ls $GOPATH/bin/cobra-cli.exe 
D:\\goprojects/bin/cobra-cli.exe

7.2 cobra-cli 初始化

该cobra-cli init [app]命令将为您创建初始应用程序代码。这是一个非常强大的应用程序，可以用正确的结构填充您的程序，这样您就可以立即享受 Cobra 的所有好处。它还可以将您指定的许可证应用于您的应用程序。

随着 Go 模块的引入，Cobra 生成器已被简化以利用模块。Cobra 生成器在 Go 模块中工作。

如果你想初始化一个新的 Go 模块：

cd $HOME/code 
mkdir myapp
cd myapp
go mod init github.com/spf13/myapp
cobra-cli init
go run main.go

cobra-cli init 也可以从子目录运行，例如cobra 生成器本身的组织方式。如果您想将应用程序代码与库代码分开，这将很有用。

可选标志：

您可以为它提供您的作者姓名和--author标志。例如cobra-cli init --author "Steve Francia spf@spf13.com"
您可以提供使用许可，--license 例如cobra-cli init --license apache
使用--viper标志自动设置viper，Viper 是 Cobra 的辅助工具，旨在提供对环境变量和配置文件的轻松处理，并将它们无缝连接到应用程序标志。

7.3 向项目添加命令

初始化 Cobra 应用程序后，您可以继续使用 Cobra 生成器向您的应用程序添加其他命令。执行此操作的命令是cobra-cli add。

假设您创建了一个应用程序，并希望为它执行以下命令：

应用服务
应用配置
应用程序配置创建

在您的项目目录（您的 main.go 文件所在的位置）中，您将运行以下命令：

cobra-cli add serve
cobra-cli add config
cobra-cli add create -p configCmd

您会注意到这个最终命令有一个-p标志。这用于将父命令分配给新添加的命令。在这种情况下，我们要将“create”命令分配给“config”命令。如果未指定，所有命令都具有 rootCmd 的默认父级。

默认情况下cobra-cli将附加Cmd到提供的名称并将此名称用作内部变量名称。指定父级时，一定要与代码中使用的变量名相匹配。

注意：命令名称使用驼峰命名法（不是 snake_case/kebab-case）。否则，您将遇到错误。例如，cobra-cli add add-user不正确，但cobra-cli add addUser有效。

运行这三个命令后，您将拥有类似于以下的应用程序结构：

▾ app/
    ▾ cmd/
        config.go
        create.go
        serve.go
        root.go
      main.go

此时您可以运行go run main.go，它会运行您的应用程序。go run main.go serve, go run main.go config,go run main.go config create连同go run main.go help serve, 等都可以。

您现在已经启动并运行了一个基于 Cobra 的基本应用程序。

参考：

Cobra 快速入门 - 专为命令行程序而生
Golang : cobra 包简介

以上是关于go 库 Cobra 现代化的命令行框架的主要内容，如果未能解决你的问题，请参考以下文章

Go语言命令行利器cobra使用教程

Go语言---小白入门-命令行库Cobra的使用

[Cobra]Go语言的命令行编写工具的快速入门

Go命令行库Cobra的核心文件root.go

Golang命令行库Cobra的使用

golang命令行库cobra的使用