golang命令行库Cobra的使用

Posted 2023-03-14

参考技术A

写了2次才写完，内容很长，翻译了很久，内容来源于Cobra github介绍。翻译完也更全面的了解了Cobra，功能相当强大完善，各种使用的场景都考虑到了。另外也扩展了一些其它知识，比如 命令行玩法 ， Levenshtein distance 等等。以下是正文：

Cobra提供简单的接口来创建强大的现代化CLI接口，比如git与go工具。Cobra同时也是一个程序, 用于创建CLI程序

Cobra是建立在结构的命令、参数和标志之上。
命令代表操作,参数和标志是这些行动的修饰符。
最好的应用程序就像读取句子。用户会知道如何使用本机应用程序，因为他们将理解如何使用它。

比如下面的例子， server 是命令， port 是标志:

在下面的命令，我们告诉Git克隆url地址bare

使用Cobra很简单。首先，使用 go get 安装最新版本

然后在你项目里引用Cobra

通常基于Cobra的应用程序将遵循下面的组织结构，当然你也可以遵循自己的接口：

在Cobra应用程序中，通常main.go文件非常空洞。它主要只干一件事：初始化Cobra。

Cobra提供自己的程序来创建你的程序并且添加你想要的命令。这是最简单的方式把Cobra添加到你的程序里。

这里 你能找到相关信息

使用Cobra，需要创建一个空的main.go文件和一个rootCmd文件。你可以选择在合适的地方添加额外的命令。

Cobra不需要特殊的构造函数。简单的就可以创建你的命令。

理想情况下你把这个放在在 app/cmd/root.go

你会另外定义标志和处理配置init()函数。

比如 cmd/root.go

你需要在main函数里执行root命令。
通常main.go文件非常空洞。它主要只干一件事：初始化Cobra。

其它的命令通常定义在cmd/目录下的自己文件内
如果你想创建一个version命令，你可以创建cmd/version.go文件，并在文件里这么写:

标志提供修饰符控制动作命令如何操作

当标志定义好了，我们需要定义一个变量来关联标志

\'持久\'表示每个在那个命令下的命令都将能分配到这个标志。对于全局标志，\'持久\'的标志绑定在root上。

Cobra默认只在目标命令上解析标志，父命令忽略任何局部标志。通过打开 Command.TraverseChildren Cobra将会在执行任意目标命令前解析标志

你同样可以通过 viper 绑定标志：

在这个例子中，永久的标记 author 被 viper 绑定, 注意 , 当用户没有给 --author 提供值， author 不会被赋值。

标记默认是可选的，如果你希望当一个标记没有设置时，命令行报错，你可以标记它为必须的

验证位置参数可以通过 Command 的 Args 字段。

内置下列验证方法

一个设置自定义验证的例子

在下面的例子，我们定义了3个命令。2个在顶级，一个（cmdTimes）是其中一个顶级命令的子命令。在这个例子里，由于没有给 rootCmd 提供 Run ，单独的root是不能运行的，必须要有子命令。

我们仅为一个命令定义了标记。

更多关于flags的文档可以在 https://github.com/spf13/pflag 找到

更完整大型程序的例子, 可以查看 Hugo .

当你的程序有子命令时，Cobra 会自动给你程序添加help命令。当你运行‘app help’，会调用help命令。另外，help同样支持其它输入命令。例如，你有一个没有任何其它配置的命令叫‘create’，当你调用‘app help create’ Corbra 将会起作用。

下面的输入是 Cobra 自动生成的。除了命令和标志的定义，其它不再需要。

help 就跟其它命令一样，并没有特殊的逻辑或行为。事实上，你也可以提供你自己help如果你想的话。

你能为默认的命令，提供你自己的help命令或模板。使用下面的方法:

后2个也将适用于任何子命令

当用户提供无效的标记或命令，Cobra 将会返回 用法 。

你可能从上面的帮助意识到，默认的帮助将被嵌入到用法里然后作为输出。

你能提供你自己的用法函数或模板给 Cobra 使用。
比如帮助，方法和模板都可以重写。

如果Version字段设置到了根命令，Cobra 会提供了一个顶层 ‘--version’标记。运行带上‘--version’标记的程序，将会按照模板版本信息。模板可以通过 cmd.SetVersionTemplate(s string) 方法修改

在命令运行前或运行后，再运行方法非常容易。 PersistentPreRun 和 PreRun 方法将会在 Run 之前执行。 PersistentPostRun 和 PostRun 方法将会在 Run 之后执行。 Persistent*Run 方法会被子命令继承，如果它们自己没有定义的话。这些方法将按照下面的属性执行：

下面的例子，2个命令都使用了上面的特性。当子命令执行的时候，它将执行根命令的 PersistentPreRun ，但不会执行根命令的 PersistentPostRun ：

输出:

Cobra 会自动输出建议，当遇到“unknown command”错误时。这使得当输入错误时， Cobra 的行为类似 git 命令。例如：

建议会基于注册的子命令自动生成。使用了 Levenshtein distance 的实现。每一个注册的命令会匹配2个距离（忽略大小写）来提供建议。

如果你希望在你的命令里，禁用建议或虚弱字符串的距离，使用：

或

你可以通过 SuggestFor 来给命令提供明确的名词建议。这个特性允许当字符串不相近，但是意思与你的命令相近，别切你也不想给该命令设置别名。比如：

Cobra 可以基于子命令，标记，等生成文档。以以下格式：

Cobra 可以生成一个bash-completion文件。如果你给命令添加更多信息，这些completions可以非常强大和灵活。更多介绍在 Bash Completions 。