Loading

Go命令行工具cobra

关于

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

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

特性

  • 简单的基于子命令的 CLIs:app serverapp fetch 等;
  • 完全兼容 POSIX(可移植操作系统接口) 的标志(包括短版和长版)
  • 嵌套子命令
  • 全局、局部和级联的标志
  • 使用 cobra init appnamecobra 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

posted @ 2023-06-28 00:30  haiyux  阅读(238)  评论(0编辑  收藏  举报