go Cobra命令行工具总结

Posted 2021-08-18 小圣.

1. 简介

Cobra是一个用Go语言实现的命令行工具。并且现在正在被很多项目使用，例如：Kubernetes,、Hugo和Github CLI等。通过使用Cobra，不仅可以快速的创建命令行界面，也可以快速开发基于Cobra的应用程序。

在cobra的git地址上有详细的使用教程，本篇文章是学习总结。cobra的git地址为：https://github.com/spf13/cobra

2. 基本概念

Cobra由三部分组成：命令(Commands )、参数(Args)和标志(Flags)。
命令（Commands）：代表行为。命令是程序的中心点，程序的每个功能都应该可以通过命令进行交互。一个命令可以有任意个子命令。
参数（Args）：命令的参数
标志（Flags）：修饰命令。它修饰命令该如何完成。

官方推荐命令格式为：

appName command args --Ffag

示例：
hugo server --port=1313
appName: hugo
command: server
flag: port

3. 安装

go get -u github.com/spf13/cobra

该命令执行完后，会在GOPATH\\bin 目录下得到一个cobra应用程序，可以通过该应用程序快速的开发cobra项目。

4. 项目创建

通过cobra应用程序可以快速初始化一个cobra项目。其语法如下：

cobra init --pkg-name=appName
示例：
mkdir newApp && cd newAPP
go mod init newAPp
cobra init --pkg-name=newApp

4.1 初始文件分析

初始化一个项目后，会在指定目录下生成主要的两个文件：
cmd/root.go和main.go。

4.1.1 main.go

package main

import "newApp/cmd"

func main() {
	cmd.Execute()
}

main.go为程序的入口，主要作用是调用了newApp/cmd文件里的Execute()函数。

4.1.2 root.go

package cmd
var cfgFile string

// rootCmd表示在没有任何子命令的情况下调用的基本命令
var rootCmd = &cobra.Command{
	Use:   "newApp",
	Short: "命令的简单描述, 当不指定这个命令时，显示这个描述。",
	Long: `命令的详细描述， 当指定这个命令时，显示这个描述.
				例如：newName -h`,
		
	// 当调用就这个命令时，就会执行到这里。			
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("newapp is called")
	},
}

// 这个函数由main()调用。只需要在根cmd上发生一次。
// Execute() 也将所有子命令添加到根命令并适当的设置标志。
func Execute() {
	cobra.CheckErr(rootCmd.Execute())
}

// init 函数，主要设置一些配置
func init() {

	cobra.OnInitialize(initConfig)

	// cobra支持全局的标志，在这里定义的标志全局可用。
	// 这个标志下面会介绍到
	//rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.new.yaml)")

	
	// cobra也支持局部标志，在这里定义的只会在命令发送时调用。
	// 下面也会介绍到
	//rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")

}

// 配置文件
func initConfig() {
	...
	...
}

5. 新增命令

cobra add commandName

示例：
cobra add serve

通过这条命令就可以为你的程序新增一条命令。重新编译后，运行一下程序就可以看到新增的命令。

而在cmd目录下可以看到增加了一个serve.go文件

var serveCmd = &cobra.Command{
	Use:   "serve",
	Short: `短的描述, 短的描述在不指定使用这个命令时调用：
				例如：newApp -h`,
	Long: `长的描述`,
	Run: func(cmd *cobra.Command, args []string) {
	},
}

func init() {
	// 把这个命令添加到rootCmd下面，就为rootCmd的子命令。
	// 同样的道理，如果想为serve添加子命令。那么就add一个命令,
	//   然后把新命令这里的代码改为：
	// 		serveCmd.AddCommand(newCommandCmd)
	rootCmd.AddCommand(serveCmd)
}

6. 设置Flag

在上面main.go文件里有两处地方设置了标志。分别是：PersistentFlags和Flags

6.1 局部Flag

var rootCmd = &cobra.Command{
	...
	...
	Run: func(cmd *cobra.Command, args []string) {
		val, err := cmd.Flags().GetBool("toggle")
		if err != nil{
			fmt.Println("getBool err: ", err)
			return
		}
		fmt.Println("toggle: ", val)
	},
}

func init() {
	cobra.OnInitialize(initConfig)

	// toggele为flag的名称
	// t为flag的简称
	// false为默认值
	// 最后一个参数为flagde 描述
	rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")

}

// 使用
> new.exe -t=true
toggle:  true         // 输出

6.2 全局Flag

var cfgFile string
var rootCmd = &cobra.Command{
	...
	...
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("cfgFile: ", cfgFile)
	},
}

func init() {
	cobra.OnInitialize(initConfig)
	
	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.new.yaml)")
}

7. 获取命令行参数

var rootCmd = &cobra.Command{
	...
	...
	Args: cobra.MinimumNArgs(1),
	Run: func(cmd *cobra.Command, args []string) {
		
		// 命令行的参数可以直接从args中获取。
		fmt.Println("args: ", args)
	},
}

在程序中，可以对参数输入进行控制。如Args:cobra.MininumNargs(1)。这个设置就是参数必须有大于等于一个。另外还有以下控制条件：

• noArgs: 如果命令有参数就会报错。
• MaximumNArgs(int)：设置命令可接受的最大参数数量 。
• ExactArgs(int)：如果命令的参数没有指定的数量就会报错。
• RangeArgs(min, max)：命令的参数必须在指定的范围内。