[系统运维]Cobra 快速入门

最近一直在看?Istio（一个?Service Mesh?框架）相关的东西，当看到其源码时发现了一个新东西?Cobra，一查却发现这是个好东西，用的地方可不少，比如：Docker、Kubernetes?等都有它的身影存在。为了更好的了解这些开源框架（如，Istio、Kubernetes?等），势必需要对?Cobra?做一个详细的了解，后续可能用到它的地方会很多。今天就?Cobra?做一个整体的介绍，让我们对它能有所认识，或许今后你的项目中也会用到它。

1、Cobra 介绍

1.1 Cobra 概述

Cobra?是一个 Golang 包，它提供了简单的接口来创建命令行程序。同时，Cobra?也是一个应用程序，用来生成应用框架，从而开发以?Cobra?为基础的应用。

1.2 主要功能

Cobra 的主要功能如下：

• 简易的子命令行模式，如?app server，?app fetch?等等。
• 完全兼容?posix?命令行模式。
• 嵌套子命令?subcommand。
• 支持全局，局部，串联?flags。
• 使用?cobra?很容易生成应用程序和命令（cobra init appname?和?cobra add cmdname）。
• 提供智能化的提示（如，输出?app srver?命令，将提示 你是要输入?app server?吗？）。
• 自动生成?commands?和?flags?的帮助信息。
• 自动生成详细的?help?信息，如?app -help。
• 自动识别帮助?flag、?-h，--help。
• 自动生成应用程序在?bash?下命令自动完成功能。
• 自动生成应用程序的?man?手册。
• 命令行别名。
• 自定义?help?和?usage?信息。
• 可选的与?viper?的紧密集成。

对于命令行程序而言，上面这些功能简直就是量身打造。

1.3 应用举例

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

（来源于：https://github.com/spf13/cobra/blob/master/projects_using_cobra.md）

• Arduino CLI
• Bleve
• CockroachDB
• Cosmos SDK
• Delve
• Docker (distribution)
• Etcd
• Gardener
• Giant Swarm’s gsctl
• Git Bump
• Github CLI
• GitHub Labeler
• Golangci-lint
• GopherJS
• Helm
• Hugo
• Istio
• Kool
• Kubernetes
• Linkerd
• Mattermost-server
• Metal Stack CLI
• Moby (former Docker)
• Nanobox/Nanopack
• OpenShift
• Ory Hydra
• Ory Kratos
• Pouch
• ProjectAtomic (enterprise)
• Prototool
• Random
• Rclone
• Skaffold
• Tendermint
• Twitch CLI
• Werf

看了这些，一个字“赞”，两个字“优秀”!

了解了?Cobra?后，再去看这些?Kubernetes、etcd、Registry?等开源项目的代码时，也就大概知道如何去看了，这也就是我学习?Cobra?的目的。

2、概念

Cobra 是基于命令（commands）、参数（arguments?）、选项（flags）而创建的。

在具体了解、使用Cobra前有一些概念需要提前知晓一下：命令（commands）、参数（arguments?）、选项（flags）这几个概念。

• commands：命令代表行为,一般表示 action，即运行的二进制命令服务。同时可以拥有子命令（children 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

再比如：

xcbeyond@xcbeyonddeMacBook-Pro ~ % docker info --help 

Usage:  docker info [OPTIONS]

Display system-wide information

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

你没有看错，像 Docker 这种这么复杂的命令都是用 Cobra 是实现的，其必有过人之处，下一节就让我们一起来看看如何实现一套属于自己的命令行工具吧！

3、Cobra 实战

实战是最好的学习方式！?本节将从一个实战带你快速入门 Cobra。

3.1 环境准备

3.1.1 前提条件&环境

• 操作系统：MacOS
• Go 环境：go 1.16
• Go 开发 IDE：VSCode

(上述环境可以个人环境而定，不做限制)

3.1.2 Cobra 安装

使用?go get?命令获取最新版本的 Cobra 库。下面命令将会安装 Cobra 及其相关依赖包：

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

下载安装完 Cobra 后，打开 GOPATH 目录，在 bin 目录下会下载好 cobra 程序（Window: cobra.exe, MacOS: cobra）。

3.1.3 工程初始化（Cobra 代码生成器）

假设现需要开发一个基于 Cobra 的 CLI 的命令行程序，命名为?cobra-demo。

由于 Cobra 提供了代码生成器的功能，我们可以直接使用 Cobra 提供的初始化命令?cobra init?进行快速初始化创建 Cobra 工程。

切换到?GOPATH?目录（如，/Users/xcbeyond/github），执行命令?cobra init <name> --pkg-name <pkgname>,如下：

xcbeyond@xcbeyonddeMacBook-Pro github % .\bin\cobra init cobra-demo --pkg-name github.com/xcbeyond/cobra-demo
Your Cobra application is ready at
/Users/xcbeyond/github/cobra-demo

初始化成功后，cobra-demo 程序目录结构如下：

.
├── cmd
│   ├── root.go
│   └── show.go
├── go.mod
├── go.sum
└── main.go

3.1.4 运行

执行命令?go run?运行：

xcbeyond@xcbeyonddeMacBook-Pro cobra-demo % go run main.go
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.

3.2 实战

这里以一个简单的?time?命令为例，实战讲解如何 Cobra 开发一个命令。

功能如下：

• show：查看当前时间。
• parse：指定时间格式 –format，parse 为 show 的子命令。

3.2.1 实现 show 命令（Command命令）

1. 添加 show 命令

   通过命令?cobra add?添加 show 命令：

   xcbeyond@xcbeyonddeMacBook-Pro cobra-demo % ../bin/cobra add show
   show created at /Users/xcbeyond/github/cobra-demo
   

   此时，项目目录下会创建一个?show.go?文件，在该文件中可完成命令的具体操作逻辑。

   下面是?show.go?文件的初始代码：

   // showCmd represents the show command
   var showCmd = &cobra.Command{
       Use:   "show",
       Short: "A brief description of your command",
       Long: `A longer description that spans multiple lines and likely contains examples
   and usage of using your command. 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.`,
       Run: func(cmd *cobra.Command, args []string) {
           fmt.Println("show called")
       },
   }
   
   func init() {
       rootCmd.AddCommand(showCmd)
   
       // Here you will define your flags and configuration settings.
   
       // Cobra supports Persistent Flags which will work for this command
       // and all subcommands, e.g.:
       // showCmd.PersistentFlags().String("foo", "", "A help for foo")
   
       // Cobra supports local flags which will only run when this command
       // is called directly, e.g.:
       // showCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
   }
   

   &cobra.Command?作为命令的定义，其中有如下变量：

   • Use：用于指定具体的命令，如：show。
   • Short：命令的简短描述。
   • Long：命令的详细描述。
   • Run：命令执行入口，用于实现命令的具体处理逻辑。

   rootCmd.AddCommand(showCmd)?命令的添加，将命令添加到根命令。（Cobra 支持命令的子命令）

2. 实现显示当前时间逻辑

   在 &cobra.Command.Run 中添加获取当前时间逻辑?time.Now()：

   var showCmd = &cobra.Command{
       Use:   "show",
       Short: "A brief description of your command",
       Long: `A longer description that spans multiple lines and likely contains examples
   and usage of using your command. 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.`,
       Run: func(cmd *cobra.Command, args []string) {
           // show current time
           fmt.Println(time.Now())
       },
   }
   

3. 修改 help 命令

   help 命令有两个，一个是 short，一个是 lang，很明显 short 命令用来定义简短的说明，lang 命令用来定义详细说明，下面我们修改 show 命令的 help:

   var showCmd = &cobra.Command{
       Use:   "show",
       Short: "Displays the current time",
       Long: `You can use the time show command to view the current time. For example:
   
   $ ./cobra-demo show
   2021-03-19 14:34:20.9320241 +0800 CST m=+0.378845301`,
       Run: func(cmd *cobra.Command, args []string) {
           // show current time
           fmt.Println(time.Now())
       },
   }
   

4. 运行

   执行 show 命令：

   xcbeyond@xcbeyonddeMacBook-Pro cobra-demo % go run main.go show
   2021-07-31 14:49:27.3582836 +0800 CST m=+0.176660901
   

   执行 show –help 命令：

   xcbeyond@xcbeyonddeMacBook-Pro cobra-demo % go run main.go show --help
   You can use the time show command to view the current time. For example:
   
   $ ./cobra-demo show
   2021-07-31 14:34:20.9320241 +0800 CST m=+0.378845301
   
   Usage:
   cobra-demo show [flags]
   
   Flags:
   -h, --help   help for show
   
   Global Flags:
           --config string   config file (default is $HOME/.cobra-demo.yaml)
   

4、总结

Cobra-demo 只是简单的阐述了由几部分组成，在实际项目中要比这复杂的很多，一般都是拥有多个子命令，但核心内容都是类似的。

?