Cobra 程序包简单解读

前言

笔者最近有改写 cobra 程序包的作业需要完成，所以去查看学习了原作者 spf13 写的cobra 程序包，这里记录一下自己的学习心得。

https://github.com/spf13/cobra

cobra 简介

cobra 是一个现代 CLI 命令行的 golang 库，是一个用于生成程序应用和命令行文件的程序

• Cobra是一个库，提供了一个简单的界面来创建类似于git＆go工具的强大的现代CLI界面。
• Cobra也是一个应用程序，它将生成您的应用程序支架，以快速开发基于Cobra的应用程序。

cobra 功能

1. 简易的子命令行模式，如app server、app get等

2. 完全兼容posix命令行模式

3. 支持全局、局部、串联flags

4. 使用cobra很容易生成应用程序和命令，使用cobra create和cobra cmdname

5. 如果命令输入有错误，将提供只能建议，如app gt，将提示gt不存在，是否是app get

6. 自动生成详细的help信息，如app help

7. 自动识别-h，–help和帮助flag

8. 自动生成应用程序在bash下命令自动改完成功能

9. 自动生成应用程序的man手册

10. 命令行别名

11. 自定义help和usage信息

12. 可选的紧密集成的viper app

获取 cobra

通过以下命令即可直接获取程序包

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

获取包后，在包的目录下运行以下命令，即可完成 cobra 的安装

go install

运行 cobra

在命令行中输入 cobra 即可查看 cobra 的相关用法：

了解上面的说明即可实验，下面以一个cmd为例子：

• cobra add pinfo : 创建一个叫 pinfo 的 golang project，之后你的命令也就叫 pinfo 了
• cobra add name: 对name 创建一个 sub-command，会直接生成一个 name.go 文件，
• 对 name.go 添肉

函数解析

Command 结构体

Command 结构体是 cobra 抽象出来的核心概念，它的实例表示一个命令或者是一个命令的子命令。下面的代码仅展示 Command 结构体中一些比较重要的字段：

type Command struct {    // 用户通过指定 Run 函数来完成命令// PreRun 和 PostRun 则允许用户在 Run 运行的前后时机执行自定义代码PersistentPreRun func(cmd *Command, args []string)PreRun func(cmd *Command, args []string)Run func(cmd *Command, args []string)PostRun func(cmd *Command, args []string)PersistentPostRun func(cmd *Command, args []string)// commands 字段包含了该命令的所有子命令commands []*Command// parent 字段记录了该命令的父命令parent *Command// 该命令的 help 子命令helpCommand *Command...
}

执行命令

cobra 包启动程序执行的代码一般为 cmd.Execute()

执行的总调用过程：

cmd.Execute()
rootCmd.Execute() 
c.ExecuteC()            
cmd.execute(flags)       
c.Run()                       

为根命令添加 help 子命令

在执行 ExecuteC() 方法时，cobra 会为根命令添加一个 help 子命令，这个子命令主要用来提供子命令的帮助信息。因为任何一个程序都需要提供输出帮助信息的方式，所以 cobra 就为它实现了一套默认的逻辑。help 子命令是通过 InitDefaultHelpCmd() 方法添加的，其实现代码如下：

// InitDefaultHelpCmd adds default help command to c.
// It is called automatically by executing the c or by calling help and usage.
// If c already has help command or c has no subcommands, it will do nothing.
func (c *Command) InitDefaultHelpCmd() {if !c.HasSubCommands() {return}if c.helpCommand == nil {c.helpCommand = &Command{Use:   "help [command]",Short: "Help about any command",Long: `Help provides help for any command in the application.
Simply type ` + c.Name() + ` help [path to command] for full details.`,Run: func(c *Command, args []string) {cmd, _, e := c.Root().Find(args)if cmd == nil || e != nil {c.Printf("Unknown help topic %#q\n", args)c.Root().Usage()} else {cmd.InitDefaultHelpFlag() // make possible 'help' flag to be showncmd.Help()}},}}c.RemoveCommand(c.helpCommand)c.AddCommand(c.helpCommand)
}

添加 help flag

除了在 InitDefaultHelpCmd() 方法中会调用 InitDefaultHelpFlag() 方法，在 execute() 方法中执行命令逻辑前也会调用 InitDefaultHelpFlag() 方法为命令添加默认的 help flag：

// InitDefaultHelpFlag adds default help flag to c.
// It is called automatically by executing the c or by calling help and usage.
// If c already has help flag, it will do nothing.
func (c *Command) InitDefaultHelpFlag() {c.mergePersistentFlags()if c.Flags().Lookup("help") == nil {usage := "help for "if c.Name() == "" {usage += "this command"} else {usage += c.Name()}c.Flags().BoolP("help", "h", false, usage)}
}

输出 help 信息

不管是 help 命令还是 help falg，最后都是通过 HelpFunc() 方法来获得输出 help 信息的逻辑：

// HelpFunc returns either the function set by SetHelpFunc for this command
// or a parent, or it returns a function with default help behavior.
func (c *Command) HelpFunc() func(*Command, []string) {if c.helpFunc != nil {return c.helpFunc}if c.HasParent() {return c.Parent().HelpFunc()}return func(c *Command, a []string) {c.mergePersistentFlags()err := tmpl(c.OutOrStdout(), c.HelpTemplate(), c)if err != nil {c.Println(err)}}
}