Golang : cobra 包簡介

時間 2019-12-06

標籤 golang cobra 簡介欄目 Go 简体版

原文原文鏈接

Cobra 是一個 Golang 包，它提供了簡單的接口來建立命令行程序。同時，Cobra 也是一個應用程序，用來生成應用框架，從而開發以 Cobra 爲基礎的應用。本文的演示環境爲 ubuntu 18.04(下圖來自互聯網)。html

主要功能

cobra 的主要功能以下，能夠說每一項都很實用：git

簡易的子命令行模式，如 app server， app fetch 等等
徹底兼容 posix 命令行模式
嵌套子命令 subcommand
支持全局，局部，串聯 flags
使用 cobra 很容易的生成應用程序和命令，使用 cobra create appname 和 cobra add cmdname
若是命令輸入錯誤，將提供智能建議，如 app srver，將提示 srver 沒有，是否是 app server
自動生成 commands 和 flags 的幫助信息
自動生成詳細的 help 信息，如 app help
自動識別幫助 flag -h，--help
自動生成應用程序在 bash 下命令自動完成功能
自動生成應用程序的 man 手冊
命令行別名
自定義 help 和 usage 信息
可選的與 viper apps 的緊密集成

cobra 中的主要概念

cobra 中有個重要的概念，分別是 commands、arguments 和 flags。其中 commands 表明行爲，arguments 就是命令行參數(或者稱爲位置參數)，flags 表明對行爲的改變(也就是咱們常說的命令行選項)。執行命令行程序時的通常格式爲：
APPNAME COMMAND ARG --FLAG
好比下面的例子：github

# server是 commands，port 是 flag
hugo server --port=1313

# clone 是 commands，URL 是 arguments，brae 是 flag
git clone URL --bare

若是是一個簡單的程序(功能單一的程序)，使用 commands 的方式可能會很囉嗦，可是像 git、docker 等應用，把這些本就很複雜的功能劃分爲子命令的形式，會方便使用(對程序的設計者來講又未嘗不是如此)。golang

建立 cobra 應用

在建立 cobra 應用前須要先安裝 cobra 包：docker

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

而後就能夠用 cobra 程序生成應用程序框架了：ubuntu

$ cobra init appname

若是不想讓應用程序在默認的目錄下，就要指定應用程序所在的絕對目錄，好比 ~/go/src/godemos/cobrademo，生成的文件以下：bash

此時的程序並無什麼功能，執行它只會輸出一些默認的提示信息：app

使用 cobra 程序生成命令代碼

除了生成應用程序框架，還能夠經過 cobra add 命令生成子命令的代碼文件，好比下面的命令會添加兩個子命令 image 和 container 相關的代碼文件：框架

$ cd ~/go/src/godemos/cobrademo
$ cobra add image
$ cobra add container

這兩條命令分別生成了 cobrademo 程序中 image 和 container 子命令的代碼，固然了，具體的功能還得靠咱們本身實現。ide

爲命令添加具體的功能

到目前爲止，咱們一共爲 cobrademo 程序添加了三個 Command，分別是 rootCmd(cobra init 命令默認生成)、imageCmd 和 containerCmd。
打開文件 root.go ，找到變量 rootCmd 的初始化過程併爲之設置 Run 方法：

Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("cobra demo program")
},

從新編譯 cobrademo 程序並不帶參數運行，此次就再也不輸出幫助信息了，而是執行了 rootCmd 的 Run 方法：

再建立一個 version Command 用來輸出當前的軟件版本。先在 cmd 目錄下添加 version.go 文件，編輯文件的內容以下：

package cmd

import (
    "fmt"

    "github.com/spf13/cobra"
)

func init() {
    rootCmd.AddCommand(versionCmd)
}

var versionCmd = &cobra.Command{
    Use:   "version",
    Short: "Print the version number of cobrademo",
    Long:  `All software has versions. This is cobrademo's`,
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("cobrademo version is v1.0")
    },
}

爲 Command 添加選項(flags)

選項(flags)用來控制 Command 的具體行爲。根據選項的做用範圍，能夠把選項分爲兩類：

persistent
local

對於 persistent 類型的選項，既能夠設置給該 Command，又能夠設置給該 Command 的子 Command。對於一些全局性的選項，比較適合設置爲 persistent 類型，好比控制輸出的 verbose 選項：

var Verbose bool
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")

local 類型的選項只能設置給指定的 Command，好比下面定義的 source 選項：

var Source string
rootCmd.Flags().StringVarP(&Source, "source", "s", "", "Source directory to read from")

該選項不能指定給 rootCmd 以外的其它 Command。
默認狀況下的選項都是可選的，但一些用例要求用戶必須設置某些選項，這種狀況 cobra 也是支持的，經過 Command 的 MarkFlagRequired 方法標記該選項便可：

var Name string
rootCmd.Flags().StringVarP(&Name, "name", "n", "", "user name (required)")
rootCmd.MarkFlagRequired("name")

命令行參數(arguments)

首先咱們來搞清楚命令行參數(arguments)與命令行選項的區別(flags/options)。以常見的 ls 命令來講，其命令行的格式爲：
ls [OPTION]... [FILE]…
其中的 OPTION 對應本文中介紹的 flags，以 - 或 -- 開頭；而 FILE 則被稱爲參數(arguments)或位置參數。通常的規則是參數在全部選項的後面，上面的 … 表示能夠指定多個選項和多個參數。

cobra 默認提供了一些驗證方法：

NoArgs - 若是存在任何位置參數，該命令將報錯
ArbitraryArgs - 該命令會接受任何位置參數
OnlyValidArgs - 若是有任何位置參數不在命令的 ValidArgs 字段中，該命令將報錯
MinimumNArgs(int) - 至少要有 N 個位置參數，不然報錯
MaximumNArgs(int) - 若是位置參數超過 N 個將報錯
ExactArgs(int) - 必須有 N 個位置參數，不然報錯
ExactValidArgs(int) 必須有 N 個位置參數，且都在命令的 ValidArgs 字段中，不然報錯
RangeArgs(min, max) - 若是位置參數的個數不在區間 min 和 max 之中，報錯

好比要讓 Command cmdTimes 至少有一個位置參數，能夠這樣初始化它：

var cmdTimes = &cobra.Command{
    Use: …
    Short: …
    Long: …
    Args: cobra.MinimumNArgs(1),
    Run: …
}

一個完整的 demo

咱們在前面建立的代碼的基礎上，爲 image 命令添加行爲(打印信息到控制檯)，併爲它添加一個子命令 cmdTimes，下面是更新後的 image.go 文件的內容(本文 demo 的完整代碼請參考這裏)：

package cmd

import (
    "fmt"

    "github.com/spf13/cobra"
    "strings"
)

// imageCmd represents the image command
var imageCmd = &cobra.Command{
    Use:   "image",
    Short: "Print images information",
    Long: "Print all images information",
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("image one is ubuntu 16.04")
        fmt.Println("image two is ubuntu 18.04")
        fmt.Println("image args are : " + strings.Join(args, " "))
    },
}

var echoTimes int
var cmdTimes = &cobra.Command{
    Use:   "times [string to echo]",
    Short: "Echo anything to the screen more times",
    Long: `echo things multiple times back to the user by providing
a count and a string.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
        for i := 0; i < echoTimes; i++ {
            fmt.Println("Echo: " + strings.Join(args, " "))
        }
    },
}

func init() {
    rootCmd.AddCommand(imageCmd)
    cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")
    imageCmd.AddCommand(cmdTimes)
}

編譯後執行命令：

$ ./cobrademo image hello
$ ./cobrademo image times -t=3 world

由於咱們爲 cmdTimes 命令設置了 Args: cobra.MinimumNArgs(1)，因此必須爲 times 子命令傳入一個參數，否則 times 子命令會報錯：

幫助信息(help command)

cobra 會自動添加 --help(-h)選項，因此咱們能夠沒必要添加該選項而直接使用：

cobra 同時還自動添加了 help 子命，默認效果和使用 --help 選項相同。若是爲 help 命令傳遞其它命令做爲參數，則會顯示對應命令的幫助信息，下面的命令輸出 image 子命令的幫助信息：

$ cobrademo help image

固然也能夠經過這種方式查看子命令的子命令的幫助文檔：

$ cobrademo help image times

除了 cobra 默認的幫助命令，咱們還能夠經過下面的方式進行自定義：

cmd.SetHelpCommand(cmd *Command)
cmd.SetHelpFunc(f func(*Command, []string))
cmd.SetHelpTemplate(s string)

提示信息(usage message)

提示信息和幫助信息很類似，只不過它是在你輸入了非法的參數、選項或命令時纔出現的：

和幫助信息同樣，咱們也能夠經過下面的方式自定義提示信息：

cmd.SetUsageFunc(f func(*Command) error)
cmd.SetUsageTemplate(s string)

在 Commnad 執行先後執行額外的操做

Command 執行的操做是經過 Command.Run 方法實現的，爲了支持咱們在 Run 方法執行的先後執行一些其它的操做，Command 還提供了額外的幾個方法，它們的執行順序以下：
   1. PersistentPreRun
   2. PreRun
   3. Run
   4. PostRun
   5. PersistentPostRun
修改 rootCmd 的初始化代碼以下：

var rootCmd = &cobra.Command{
    Use:   "cobrademo",
    Short: "sparkdev's cobra demo",
    Long: "the demo show how to use cobra package",
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PersistentPreRun with args: %v\n", args)
    },
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PreRun with args: %v\n", args)
    },
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Printf("cobra demo program, with args: %v\n", args)
    },
    PostRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PostRun with args: %v\n", args)
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
        fmt.Printf("Inside rootCmd PersistentPostRun with args: %v\n", args)
    },
}