golang常用库之-命令行工具 Cobra(眼镜蛇)

golang常用库之-命令行工具 Cobra(眼镜蛇)

一、spf13/cobra

spf13/cobra 和 urfave/cli 是Go的2个优秀命令行工具：

名称	star	仓库地址	应用项目
spf13/cobra	25.6k	https://github.com/spf13/cobra	docker, kubernetes, istio， hugo …
urfave/cli	17.5k	https://github.com/urfave/cli	drone, peach, gogs …

1. 项目作者

spf13 前go团队成员,viper hugo 等等都是大牛spf13的作品。
大牛推特：https://twitter.com/spf13
https://github.com/spf13

二、cobra

https://cobra.dev/

美: [ˈkoʊbrə]
n. 眼镜蛇（毒蛇，分布于亚洲和非洲）

cobra是一种创建强大的现代CLI应用程序的库。

cobra用于许多GO项目，如Kubernetes，Hugo和Github Cli，以命名几个。此列表包含使用cobra的项目列表。

Cobra既是一个用来创建强大的现代命令行应用的库，又是一个用来生成应用和命令文件的脚手架。
很多流行的Go项目都使用Cobra，例如Kubernetes, Hugo, rkt, etcd, Moby (former Docker), Docker (distribution), OpenShift, Delve, GopherJS, CockroachDB, Bleve, ProjectAtomic (enterprise), Giant Swarm’s gsctl, Nanobox/Nanopack, rclone, nehm, Pouch, Istio, Prototool, mattermost-server, Gardener, Linkerd等。

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

2. 概念

命令(Commands)，参数(Args)和标识(Flags)是Cobra重要的三个概念。

• 命令(Commands)代表动作
• 参数(Args)代表事件
• 标示(Flags)是对动作的修饰

Cobra基于三个基本概念commands,arguments和flags。其中commands代表行为，arguments代表数值，flags代表对行为的改变。

hugo server --port=1313

• hugo：根命令
• server：子命令
• –port：标志

再看个带有参数的例子：

git clone URL --bare

• git：根命令
• clone：子命令
• URL：参数，即 clone 作用的对象
• –bare：标志

总结：
commands 代表行为
arguments 代表行为作用的对象
flags 是行为的修饰符

3. 标志

Cobra 中有两种标志：持久标志 ( Persistent Flags ) 和 本地标志 ( Local Flags ) 。

持久标志：指所有的 commands 都可以使用该标志。比如：–verbose ，–namespace
本地标志：指特定的 commands 才可以使用该标志。

全局的：

RootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra_exp1.yaml)")

局部的：

RootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")

区别就在 RootCmd 后面的是 Flags 还是 PersistentFlags

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)
  }
}

4. golang命令行库cobra的使用

Golang之使用Cobra
参考URL: https://o-my-chenjian.com/2017/09/20/Using-Cobra-With-Golang/

Cobra 非常易用，首先使用 go get 命令安装最新版本。

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

下载完成后安装 cobra 工具，在 $GOPATH/bin 会生成可执行文件。

将生成的 cobra 工具放到 $PATH 目录下，可以看到：

[root@localhost ~]# cp -a $GOPATH/bin/cobra /usr/local/bin
[root@localhost ~]# cobra
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.

Usage:
  cobra [command]

Available Commands:
  add         Add a command to a Cobra Application
  help        Help about any command
  init        Initialize a Cobra Application

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 cobra
  -l, --license string   name of license for the project
      --viper            use Viper for configuration (default true)

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

从截图上可以看到，输出的结果中主要包括三部分：Usage、Available Commands、Flags。其中 Usage 是告诉你该命令总的用法， Available Commands 告诉你有哪些子命令，Flags 则是告诉你可以用哪些参数。

总的来说，一个优秀的程序命令由三部分组成：主命令、子命令、参数。主命令是整个程序的入口，子命令是程序内各种主要的功能，参数则是告诉程序如何执行这些功能。

接下来我们初始化一个项目。

4.1 初始化

通过 cobra init 初始化 demo 项目：

[root@localhost ~]# cd $GOPATH/src 
[root@localhost src]# cobra init demo --pkg-name=demo
Your Cobra applicaton is ready at
/root/go/src/demo

当前项目结构为：

demo
├── cmd
│   └── root.go
├── LICENSE
└── main.go

可以看到初始化后的项目非常简单，主要是 main.go 和 root.go 文件。在编写代码之前，我们先分析下目前代码的逻辑。

代码分析
先查看下入口文件 main.go。代码逻辑很简单，就是调用 cmd 包里 Execute()函数:

package main

import "demo/cmd"

func main() {
  cmd.Execute()
}

再看下 root.go 中 rootCmd 的字段：

...

var rootCmd = &cobra.Command{
  Use:   "demo",
  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() {
  if err := rootCmd.Execute(); err != nil {
    fmt.Println(err)
    os.Exit(1)
  }
}

...

简单说明下：

• Use：命令名
• Short & Long：帮助信息的文字内容
• Run：运行命令的逻辑

5. Cobra使用 demo

package main
import (
	"fmt"
	"github.com/spf13/cobra"
	"strings"
)

func main() {
	var cmdPull = &cobra.Command{
		Use:   "pull [OPTIONS] NAME[:TAG|@DIGEST]",
		Short: "Pull an image or a repository from a registry",
		Run: func(cmd *cobra.Command, args []string) {
			fmt.Println("Pull: " + strings.Join(args, " "))
		},
	}

	var rootCmd = &cobra.Command{Use: "docker"}
	rootCmd.AddCommand(cmdPull)
	rootCmd.Execute()
}

6. 项目实战

参考学习：
https://github.com/marmotedu/iam/blob/master/pkg/app/app.go

三、Cobra Command

基本上所有命令相关的功能都定义在Command结构体中, 使用cobar核心就是实例化这个结构体~

cmd := &cobra.Command{
	Use:   "echo",
}
//设置输出为标识输出
cmd.SetOut(os.Stdout)
cmd.Flags().SortFlags = false

其他参考

Golang之使用Cobra
参考URL: https://o-my-chenjian.com/2017/09/20/Using-Cobra-With-Golang/
cobra：生成解析命令行参数工具
参考URL: https://www.cnblogs.com/pxlsdz/p/15841231.html
Go 优秀库推荐 - 命令行工具 cobra
参考URL: https://juejin.cn/post/6844903828001652749
使用 Cobra 构建命令行工具
参考URL: https://blog.csdn.net/jiangyou0k/article/details/99854314