1.  
  2. 主页
  3.  / 
  4. Go 每日一库
  5.  / 
  6. Go 每日一库之 cobra 使用详解

Go 每日一库之 cobra 使用详解

简介

cobra是一个命令行程序库,可以用来编写命令行程序。

同时,它也提供了一个脚手架, 用于生成基于 cobra 的应用程序框架。

非常多知名的开源项目都使用了 cobra 库构建命令行,如KubernetesHugoetcd等等。

本文介绍 cobra 库的基本使用和一些有趣的特性。

快速使用

第三方库都需要先安装,后使用。

下面命令安装了cobra生成器程序和 cobra 库:

如果出现了golang.org/x/text库找不到之类的错误,需要手动从 GitHub 上下载该库,再执行上面的安装命令。

我们实现一个简单的命令行程序 git,当然这不是真的 git,只是模拟其命令行。最终还是通过os/exec库调用外部程序执行真实的 git 命令,返回结果。 所以我们的系统上要安装 git,且 git 在可执行路径中。

目前我们只添加一个子命令version。目录结构如下:

root.go

version.go

main.go文件中只是调用命令入口:

为了编码方便,在helpers.go中封装了调用外部程序和错误处理函数:

每个 cobra 程序都有一个根命令,可以给它添加任意多个子命令。我们在version.goinit函数中将子命令添加到根命令中。

编译程序。注意,不能直接go run main.go,这已经不是单文件程序了。如果强行要用,请使用go run .

cobra 自动生成的帮助信息,very cool:

单个子命令的帮助信息:

调用子命令:

未识别的子命令:

编译时可以将main.exe改成git,用起来会更有感觉🤩。

使用 cobra 构建命令行时,程序的目录结构一般比较简单,推荐使用下面这种结构:

每个命令实现一个文件,所有命令文件存放在cmd目录下。外层的main.go仅初始化 cobra。

特性

cobra 提供非常丰富的功能:

  • 轻松支持子命令,如app serverapp fetch等;
  • 完全兼容 POSIX 选项(包括短、长选项);
  • 嵌套子命令;
  • 全局、本地层级选项。可以在多处设置选项,按照一定的顺序取用;
  • 使用脚手架轻松生成程序框架和命令。

首先需要明确 3 个基本概念:

  • 命令(Command):就是需要执行的操作;
  • 参数(Arg):命令的参数,即要操作的对象;
  • 选项(Flag):命令选项可以调整命令的行为。

下面示例中,server是一个(子)命令,--port是选项:

下面示例中,clone是一个(子)命令,URL是参数,--bare是选项:

命令

在 cobra 中,命令和子命令都是用Command结构表示的。Command有非常多的字段,用来定制命令的行为。

在实际中,最常用的就那么几个。我们在前面示例中已经看到了Use/Short/Long/Run

Use指定使用信息,即命令怎么被调用,格式为name arg1 [arg2]name为命令名,后面的arg1为必填参数,arg3为可选参数,参数可以多个。

Short/Long都是指定命令的帮助信息,只是前者简短,后者详尽而已。

Run是实际执行操作的函数。

定义新的子命令很简单,就是创建一个cobra.Command变量,设置一些字段,然后添加到根命令中。例如我们要添加一个clone子命令:

其中Use字段clone url [destination]表示子命令名为clone,参数url是必须的,目标路径destination可选。

我们将程序编译为mygit可执行文件,然后将它放到$GOPATH/bin中。我喜欢将$GOPATH/bin放到$PATH中,所以可以直接调用mygit命令了:

大家可以继续添加命令。但是我这边只是偷了个懒,将操作都转发到实际的 git 去执行了。这确实没什么实际的用处。

有这个思路,试想一下,我们可以结合多个命令实现很多有用的工具,例如打包工具😉。

选项

cobra 中选项分为两种,一种是永久选项,定义它的命令和其子命令都可以使用。通过给根命令添加一个选项定义全局选项。 另一种是本地选项,只能在定义它的命令中使用。

cobra 使用pflag解析命令行选项。pflag使用上基本与flag相同,该系列文章有一篇介绍flag库的,Go 每日一库之 flag

flag一样,存储选项的变量也需要提前定义好:

设置永久选项:

设置本地选项:

两种参数都是相同的,长选项/短选项名、默认值和帮助信息。

下面,我们通过一个案例来演示选项的使用。

假设我们要做一个简单的计算器,支持加、减、乘、除操作。并且可以通过选项设置是否忽略非数字参数,设置除 0 是否报错。 显然,前一个选项应该放在全局选项中,后一个应该放在除法命令中。程序结构如下:

这里展示divide.goroot.go,其它命令文件都类似。完整代码我放在GitHub上了。

divide.go

root.go

divide.go中定义了如何处理除 0 错误的选项,在root.go中定义了如何处理解析错误的选项。

选项枚举如下:

其实命令的执行逻辑并不复杂,就是将参数转为float64

然后执行相应的运算,输出结果。

测试程序:

默认情况,解析错误被忽略,只计算格式正确的参数的结果:

设置解析失败的处理,2 表示退出程序,3 表示 panic(看上面的枚举):

至于除 0 选项大家自己试试。

细心的朋友应该都注意到了,该程序还有一些不完善的地方。例如这里如果输入非数字参数,该参数也会显示在结果中:

感兴趣可以自己完善一下~

脚手架

通过前面的介绍,我们也看到了其实 cobra 命令的框架还是比较固定的。这就有了工具的用武之地了,可极大地提高我们的开发效率。

前面安装 cobra 库的时候也将脚手架程序安装好了。下面我们介绍如何使用这个生成器。

使用cobra init命令创建一个 cobra 应用程序:

其中scaffold为应用程序名,后面通过pkg-name选项指定包路径。生成的程序目录结构如下:

这个项目结构与之前介绍的完全相同,也是 cobra 推荐使用的结构。同样地,main.go也仅仅是入口。

root.go中,工具额外帮我们生成了一些代码。

在根命令中添加了配置文件选项,大部分应用程序都需要配置文件:

在初始化完成的回调中,如果发现该选项为空,则默认使用主目录下的.scaffold.yaml文件:

这里用到了我前几天介绍的go-homedir库。

配置文件的读取使用了 spf13 自己的开源项目viper(毒龙?真是起名天才)。

除了代码文件,cobra 还生成了一个 LICENSE 文件。

现在这个程序还不能做任何事情,我们需要给它添加子命令,使用cobra add命令:

该命令在cmd目录下新增了date.go文件。基本结构已经搭好了,剩下的就是修改一些描述,添加一些选项了。

我们现在实现这样一个功能,根据传入的年、月,打印这个月的日历。如果没有传入选项,使用当前的年、月。

选项定义:

修改dateCmdRun函数:

showCalendar函数就是利用time提供的方法实现的,这里就不赘述了。感兴趣可以去我的 GitHub 上查看实现。

看看程序运行效果:

可以再为这个程序添加其他功能,试一试吧~

其他

cobra 提供了非常丰富的特性和定制化接口,例如:

  • 设置钩子函数,在命令执行前、后执行某些操作;
  • 生成 Markdown/ReStructed Text/Man Page 格式的文档;
  • 等等等等。

由于篇幅限制,就不一一介绍了。有兴趣可自行研究。cobra 库的使用非常广泛,很多知名项目都有用到,前面也提到过这些项目。 学习这些项目是如何使用 cobra 的,可以从中学习 cobra 的特性和最佳实践。这也是学习开源项目的一个很好的途径。

文中所有示例代码都已上传至我的 GitHub,Go 每日一库,https://github.com/darjun/go-daily-lib/tree/master/cobra。

参考

  1. cobra GitHub 仓库
这篇文章对您有用吗?

我们要如何帮助您?

发表评论

邮箱地址不会被公开。 必填项已用*标注