Go命令行工具cobra

关于

Cobra 是 Go 的 CLI 框架。它包含一个用于创建功能强大的现代 CLI 应用程序的库，以及一个用于快速生成基于 Cobra 的应用程序和命令文件的工具。

Cobra 由 Go 项目成员和 hugo 作者 spf13 创建，已经被许多流行的 Go 项目采用，比如 kubernetes、docker等

特性

简单的基于子命令的 CLIs：app server、app fetch 等；
完全兼容 POSIX（可移植操作系统接口）的标志（包括短版和长版）
嵌套子命令
全局、局部和级联的标志
使用 cobra init appname 和 cobra add cmdname 轻松生成应用程序和命令
智能提示（app srver ...did you mean app server）
自动生成命令和标志的帮助
自动识别 -h、--help 等帮助标识
自动为你的应用程序生成的 bash 自动完成
自动为你的应用程序生成 man 手册
命令别名，以便你可以更改内容而不会破坏它们
定义自己的帮助，用法等的灵活性。
可选与 viper 紧密集成，可用于 12factor 应用程序

概念

Cobra 构建在命令（commands）、参数（arguments）和标志（flags）上。

Commands 代表动作，Args 是事物，Flags 是这些动作的修饰符。

最好的应用程序在使用时会像句子一样读起来。用户将知道如何使用该应用程序，因为他们将自然地了解如何使用它。

遵循的模式是 APPNAME VERB NOUN --ADJECTIVE。或 APPNAME COMMAND ARG --FLAG

一些真实的例子可以更好地说明这一点。

在以下示例中，server 是命令，port 是标志：

hugo server --port=1313

在此命令中，我们告诉 Git 克隆 url 的内容：

git clone URL --bare

命令（Command）

命令是应用程序的核心。应用程序提供的每一个交互都包含在 Command 中。一个命令可以有子命令和可选的运行一个动作。

在上面的示例中，server 是命令。

Cobra.Command API)

标志（Flags）

一个标志是一种修饰命令行为的方式。Cobra 支持完全符合 [https://zh.wikipedia.org/wiki/可移植操作系统接口) 包。

Cobra 命令可以定义一直保留到子命令的标志和仅可用于该命令的标志。

在上面的例子中，port 是标志。

标志的功能是 pflag 库提供的，该库是一个标准库的 fork，在维护相同接口的基础上兼容了 POSIX（可移植操作系统接口）。

简单使用

// 目录结构

├── add

│   └── add.go

├── go.mod

├── go.sum

└── main.go

// main.go

package main

import (

	"log"

	"test/add"

	"github.com/spf13/cobra"

)

var rootCmd = &cobra.Command{

	Use:     "test",

	Short:   "测试",

	Long:    `我要写博客做个测试呢,这是个常提示`,

	Version: "v1.1",

}

func init() {

	rootCmd.AddCommand(add.CmdAdd)

}

func main() {

	if err := rootCmd.Execute(); err != nil {

		log.Fatal(err)

	}

}

// add/add.go

package add

import (

	"fmt"

	"github.com/spf13/cobra"

)

var CmdAdd = &cobra.Command{

	Use:   "add",

	Short: "新键",

	Long:  "新建个文件",

	RunE:  RunE,

}

var path string

func init() {

	CmdAdd.Flags().StringVarP(&path, "path", "p", path, "file path")

}

func RunE(cmd *cobra.Command, args []string) error {

	fmt.Println("假装创建个文件 path=", path)

	return nil

}

执行结果

# go run main.go --help

我要写博客做个测试呢,这是个常提示

Usage:

  test [command]

Available Commands:

  add         新键

  completion  Generate the autocompletion script for the specified shell

  help        Help about any command

Flags:

  -h, --help      help for test

  -v, --version   version for test

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

# go run main.go add --help

新建个文件

Usage:

  test add [flags]

Flags:

  -h, --help          help for add

  -p, --path string   file path

# go run main.go add --path=/user/pass

假装创建个文件 path= /user/pass

# go run main.go --version

test version v1.1

Command参数

例子中的cobra.Command是个结构体，有很多字段，都是做什么用的呢？

这些参数是Go语言中cobra库中的Command结构体的字段，用于定义命令行工具的行为和选项。它们的作用如下：

Use: 命令名称。
Aliases: 命令的别名。
SuggestFor: 命令建议使用的单词列表。
Short: 命令简短描述。
GroupID: 命令所属的命令组。
Long: 命令详细描述。
Example: 命令的使用示例。
ValidArgs: 命令接受的参数列表。
ValidArgsFunction: 命令用于提供动态参数补全的函数。
Args: 命令的位置参数列表。
ArgAliases: 位置参数的别名。
BashCompletionFunction: 生成Bash补全的函数。
Deprecated: 命令是否已经过时的标志。
Annotations: 命令的附加注释信息。
Version: 命令版本号。
PersistentPreRun: 每次执行该命令之前都会执行的函数。
PersistentPreRunE: 每次执行该命令之前都会执行的返回错误的函数。
PreRun: 每次执行该命令之前都会执行的函数。
PreRunE: 每次执行该命令之前都会执行的返回错误的函数。
Run: 执行命令的函数。
RunE: 执行命令的返回错误的函数。
PostRun: 每次执行该命令之后都会执行的函数。
PostRunE: 每次执行该命令之后都会执行的返回错误的函数。
PersistentPostRun: 每次执行该命令之后都会执行的函数。
PersistentPostRunE: 每次执行该命令之后都会执行的返回错误的函数。
FParseErrWhitelist : 忽略特定的解析错误
CompletionOptions :控制 shell 自动完成的选项
TraverseChildren: 解析父命令的标志后再执行子命令
Hidden : 隐藏命令，不在可用命令列表中显示
SilenceErrors : 静默下游错误
SilenceUsage : 静默错误时不显示用法
DisableFlagParsing : 禁用标志解析
DisableAutoGenTag : 禁用自动生成的标记
DisableFlagsInUseLine : 在打印帮助或生成文档时禁用“[flags]”在用法行中的添加
DisableSuggestions : 禁用基于Levenshtein距离的建议
SuggestionsMinimumDistance : 显示建议的最小Levenshtein距离

Reference