Cobra框架使用手册

cobra框架使用手册

cobra是go语言的一个库，可以用于编写命令行工具。

概念

Cobra 结构由三部分组成：命令 (commands)、参数 (arguments)、标志 (flags)。最好的应用程序在使用时读起来像句子，要遵循的模式是APPNAME VERB NOUN --ADJECTIVE。

安装

此命令将安装cobra生成器可执行文件以及库及其依赖项：

go get -u github.com/spf13/cobra
#接下来导入
import "github.com/spf13/cobra"

使用Cobra生成器

这是将Cobra合并到应用程序最简单的方法。

#首先编译cobra命令,将在$GOPATH/bin下创建cobra的可执行文件
go get github.com/spf13/cobra/cobra

cobra init [app]

创建初始应用程序代码，用正确的结构填充应用程序，可以立即享受cobra的好处，还会自动将您指定的许可证应用于您的应用程序。

可以在当前目录中运行，也可在指定现有项目的相对路径，如果目录不存在，将会创建。

#注意：非空目录上运行将不在失败，--pkg-name是必须的
mkdir -p newApp && cd newApp
cobra init --pkg-name github.com/spf13/newApp

cobra init --pkg-name github.com/spf13/newApp path/to/newApp

cobra add

一旦应用程序初始化后，cobra就可以为您创建其他命令，假设需要如下命令：

• app server
• app config
• app config create

在项目根目录下（mian.go所在的目录）运行

cobra add server
cobra add config
cobra add create -p 'configCmd'

注意：使用camelCase（not snake_case/kebab-case）命名

然后将会看到类似下面的程序结构：

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

此时运行go run main.go、go run main.go serve/config/config create/help serve等都会工作。

显然，您还没有将自己的代码添加到这些中，命令就已经准备就绪。

配置Cobra生成器：

如果提供一个简单的配置文件，那么Cobra生成器将更易于使用。

示例配置~/.cobra.yaml：

author: Steve Francia <spf@spf13.com>
license: MIT

还可以使用内置许可证，还可以通过设置license为none来指定无许可证或者指定一个自定义许可证。

author: Steve Francia <spf@spf13.com>
year: 2020
license:
  header: This file is part of CLI application foo.
  text: |
    {{ .copyright }}

    This is my license. There are many like it, but this one is mine.
    My license is my best friend. It is my life. I must master it as I must
    master my life.

LICENSE文件的内容为：

Copyright  2020 Steve Francia <spf@spf13.com>

This is my license. There are many like it, but this one is mine.
My license is my best friend. It is my life. I must master it as I must
master my life.

使用Cobra库

要手动实现Cobra，需要创建一个mian.go文件和rootCmd文件。

创建 rootCmd

Cobra不需要任何特殊的构造器。只需创建命令。

place this file in app/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.Fprintln(os.Stderr, err)
    os.Exit(1)
  }
}

还可以在init()函数中定义标志和句柄配置：

package cmd

import (
	"fmt"
	"os"

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

var (
	// Used for flags.
	cfgFile     string
	userLicense string

	rootCmd = &cobra.Command{
		Use:   "cobra",
		Short: "A generator for Cobra based Applications",
		Long: `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.`,
	}
)

// Execute executes the root command.
func Execute() error {
	return rootCmd.Execute()
}

func init() {
	cobra.OnInitialize(initConfig)

	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")
	rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "author name for copyright attribution")
	rootCmd.PersistentFlags().StringVarP(&userLicense, "license", "l", "", "name of license for the project")
	rootCmd.PersistentFlags().Bool("viper", true, "use Viper for configuration")
	viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
	viper.BindPFlag("useViper", rootCmd.PersistentFlags().Lookup("viper"))
	viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
	viper.SetDefault("license", "apache")

	rootCmd.AddCommand(addCmd)
	rootCmd.AddCommand(initCmd)
}

func initConfig() {
	if cfgFile != "" {
		// Use config file from the flag.
		viper.SetConfigFile(cfgFile)
	} else {
		// Find home directory.
		home, err := os.UserHomeDir()
		cobra.CheckErr(err)

		// Search config in home directory with name ".cobra" (without extension).
		viper.AddConfigPath(home)
		viper.SetConfigType("yaml")
		viper.SetConfigName(".cobra")
	}

	viper.AutomaticEnv()

	if err := viper.ReadInConfig(); err == nil {
		fmt.Println("Using config file:", viper.ConfigFileUsed())
	}
}

创建 main.go

main.go也很简单，只有一个目标：初始化cobra

package main

import (
  "{pathToYourApp}/cmd"
)

func main() {
  cmd.Execute()
}

创建其他命令

通常每个命令在cmd/目录下都有自己的文件，如果要创建版本命令，可以创建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 Hugo's`,
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
  },
}

返回和处理错误

如果你希望返回一个错误给命令的调用者，可以使用RunE。

package cmd

import (
  "fmt"

  "github.com/spf13/cobra"
)

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

var tryCmd = &cobra.Command{
  Use:   "try",
  Short: "Try and possibly fail at something",
  RunE: func(cmd *cobra.Command, args []string) error {
    if err := someFunc(); err != nil {
	return err
    }
    return nil
  },
}

可以在execute函数调用中捕获错误。

使用标志

标志提供修饰符来控制操作命令的操作方式。

为命令指定flags

由于标志是在不同的位置定义和使用的，因此我们需要在外部定义一个具有正确作用域的变量来分配要使用的标志。

var Verbose bool
var Source string

• 持久标志：该标志可用于分配给它的命令以及该命令下的每个命令。

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

• 局部标志：只适用于特定命令。

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

父命令上的本地标志：

默认情况下，Cobra只解析目标命令上的局部标志，而忽略父命令上的任何局部标志。

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

用配置绑定标志：

使用viper绑定flags

var author string

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

注意：当用户未提供--author标志时，变量author将不会设置为config中的值。

必须标志：

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

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

位置参数和自定义参数：

可以使用命令的Args字段指定位置参数

var cmd = &cobra.Command{
  Short: "hello",
  Args: func(cmd *cobra.Command, args []string) error {
    if len(args) < 1 {
      return errors.New("requires a color argument")
    }
    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!")
  },
}

示例

在下面的示例中，我们定义了三个命令。两个是顶级命令，一个（cmdTimes）是顶级命令之一的子命令。在这种情况下，根是不可执行的，这意味着需要一个子命令。这是通过不为“rootCmd”提供“Run”来实现的。

我们只为一个命令定义了一个标志。

package main

import (
  "fmt"
  "strings"

  "github.com/spf13/cobra"
)

func main() {
  var echoTimes int

  var cmdPrint = &cobra.Command{
    Use:   "print [string to print]",
    Short: "Print anything to the screen",
    Long: `print is for printing anything back to the screen.
For many years people have printed back to the screen.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Print: " + strings.Join(args, " "))
    },
  }

  var cmdEcho = &cobra.Command{
    Use:   "echo [string to echo]",
    Short: "Echo anything to the screen",
    Long: `echo is for echoing anything back.
Echo works a lot like print, except it has a child command.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Echo: " + strings.Join(args, " "))
    },
  }

  var cmdTimes = &cobra.Command{
    Use:   "times [string to echo]",
    Short: "Echo anything to the screen more times",
    Long: `echo things multiple times back to the user by providing
a count and a string.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      for i := 0; i < echoTimes; i++ {
        fmt.Println("Echo: " + strings.Join(args, " "))
      }
    },
  }

  cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")

  var rootCmd = &cobra.Command{Use: "app"}
  rootCmd.AddCommand(cmdPrint, cmdEcho)
  cmdEcho.AddCommand(cmdTimes)
  rootCmd.Execute()
}

Help Cmmand

当您有子命令时，Cobra会自动将help命令添加到应用程序中。当用户运行app help时，将调用此函数。此外，help还支持所有其他命令作为输入。例如，您有一个名为“create”的命令，没有任何附加配置；调用“app help create”时，Cobra将起作用。每个命令都会自动添加“-help”标志。

自定义help命令和模版

cmd.SetHelpCommand(cmd *Command)
cmd.SetHelpFunc(f func(*Command, []string))
cmd.SetHelpTemplate(s string)

Useage Message

当用户提供无效标志或无效命令时，Cobra会通过向用户显示“usage”（使用情况）来响应。

自定义useage

cmd.SetUsageFunc(f func(*Command) error)
cmd.SetUsageTemplate(s string)

参考链接：

https://github.com/spf13/cobra/blob/master/user_guide.md