現代化的命令行框架：Cobra 全解

學習地址：https://github.com/spf13/cobra

​ Cobra 既是一個可以創建強大的現代 CLI 應用程序的庫，也是一個可以生成應用和命令文件的程序。有許多大型項目都是用 Cobra 來構建應用程序的，例如 Kubernetes、Docker、etcd、Rkt、Hugo 等。

​ Cobra 建立在 commands、arguments 和 flags 結構之上。commands 代表命令，arguments 代表非選項參數，flags 代表選項參數（也叫標志）。一個好的應用程序應該是易懂的，用戶可以清晰地知道如何去使用這個應用程序。應用程序通常遵循如下模式：APPNAME VERB NOUN --ADJECTIVE或者APPNAME COMMAND ARG --FLAG，例如：

kubectl get pod --all-namespace # get 是一個命令，pod 是一個非選項參數，all-namespace 是一個選項參數

這里，VERB 代表動詞，NOUN 代表名詞，ADJECTIVE 代表形容詞

1、使用 Cobra 庫創建命令

​ 如果要用 Cobra 庫編碼實現一個應用程序，需要首先創建一個空的 main.go 文件和一個 rootCmd 文件，之后可以根據需要添加其他命令。具體步驟如下：

1.1、創建 rootCmd。

mkdir -p newApp2 && cd newApp2

通常情況下，我們會將 rootCmd 放在文件 cmd/root.go 中。

var rootCmd = &cobra.Command{
    Use:   "newApp2",
    Short: "newApp2 is a demo project",
    Long: `newApp2 is a demo project...`,
    Run: func(cmd *cobra.Command, args []string) {
        cmd.Help()
    },
}

func Execute() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Println(err)
        os.Exit(1)
    }
}

還可以在 init() 函數中定義標志和處理配置，例如 cmd/root.go。

import (
  "fmt"
  "os"

  homedir "github.com/mitchellh/go-homedir"
  "github.com/spf13/cobra"
  "github.com/spf13/viper"
)

var (
    cfgFile     string
    projectBase string
    userLicense string
)

func init() {
  cobra.OnInitialize(initConfig)
  rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")
  rootCmd.PersistentFlags().StringVarP(&projectBase, "projectbase", "b", "", "base project directory eg. github.com/spf13/")
  rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "Author name for copyright attribution")
  rootCmd.PersistentFlags().StringVarP(&userLicense, "license", "l", "", "Name of license for the project (can provide `licensetext` in config)")
  rootCmd.PersistentFlags().Bool("viper", true, "Use Viper for configuration")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
  viper.BindPFlag("projectbase", rootCmd.PersistentFlags().Lookup("projectbase"))
  viper.BindPFlag("useViper", rootCmd.PersistentFlags().Lookup("viper"))
  viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
  viper.SetDefault("license", "apache")
}

func initConfig() {
  // Don't forget to read config either from cfgFile or from home directory!
  if cfgFile != "" {
    // Use config file from the flag.
    viper.SetConfigFile(cfgFile)
  } else {
    // Find home directory.
    home, err := homedir.Dir()
    if err != nil {
      fmt.Println(err)
      os.Exit(1)
    }

    // Search config in home directory with name ".cobra" (without extension).
    viper.AddConfigPath(home)
    viper.SetConfigName(".cobra")
  }

  if err := viper.ReadInConfig(); err != nil {
    fmt.Println("Can't read config:", err)
    os.Exit(1)
  }
}

1.2、創建 main.go。
我們還需要一個 main 函數來調用 rootCmd，通常我們會創建一個 main.go 文件，在 main.go 中調用 rootCmd.Execute() 來執行命令：

package main

import (
  "{pathToYourApp}/cmd"
)

func main() {
  cmd.Execute()
}

需要注意，main.go 中不建議放很多代碼，通常只需要調用 cmd.Execute() 即可。

1.3、添加命令。

​ 除了 rootCmd，我們還可以調用 AddCommand 添加其他命令，通常情況下，我們會把其他命令的源碼文件放在 cmd/ 目錄下，例如，我們添加一個 version 命令，可以創建 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 Hugo",
  Long:  `All software has versions. This is Hugo's`,
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hugo Static Site Generator v0.9 -- HEAD")
  },
}

本示例中，我們通過調用rootCmd.AddCommand(versionCmd)給 rootCmd 命令添加了一個 versionCmd 命令。

1.44、編譯並運行。

​ 將 main.go 中{pathToYourApp}替換為對應的路徑，例如本示例中 pathToYourApp 為github.com/marmotedu/gopractise-demo/cobra/newApp2。

$ go mod init github.com/marmotedu/gopractise-demo/cobra/newApp2

$ go build -v .

$ ./newApp2 -h

A Fast and Flexible Static Site Generator built with
love by spf13 and friends in Go.
Complete documentation is available at http://hugo.spf13.com

Usage:
hugo [flags]
hugo [command]

Available Commands:
help Help about any command
version Print the version number of Hugo

Flags:
-a, --author string Author name for copyright attribution (default "YOUR NAME")
--config string config file (default is $HOME/.cobra.yaml)
-h, --help help for hugo
-l, --license licensetext Name of license for the project (can provide licensetext in config)
-b, --projectbase string base project directory eg. github.com/spf13/
--viper Use Viper for configuration (default true)

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

通過步驟一、步驟二、步驟三，我們就成功創建和添加了 Cobra 應用程序及其命令。

2、使用標志

Cobra 可以跟 Pflag 結合使用，實現強大的標志功能。使用步驟如下：

2.1、使用持久化的標志。

標志可以是“持久的”，這意味着該標志可用於它所分配的命令以及該命令下的每個子命令。可以在 rootCmd 上定義持久標志：

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

2.2、使用本地標志。

也可以分配一個本地標志，本地標志只能在它所綁定的命令上使用：

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

--source標志只能在 rootCmd 上引用，而不能在 rootCmd 的子命令上引用。
2.3、將標志綁定到 Viper。

我們可以將標志綁定到 Viper，這樣就可以使用 viper.Get() 獲取標志的值。

var author string

func init() {
  rootCmd.PersistentFlags().StringVar(&author, "author", "YOUR NAME", "Author name for copyright attribution")
  viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
}

2.4、設置標志為必選。

默認情況下，標志是可選的，我們也可以設置標志為必選，當設置標志為必選，但是沒有提供標志時，Cobra 會報錯。

rootCmd.Flags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkFlagRequired("region")

3、非選項參數驗證

​ 在命令的過程中，經常會傳入非選項參數，並且需要對這些非選項參數進行驗證，Cobra 提供了機制來對非選項參數進行驗證。可以使用 Command 的 Args 字段來驗證非選項參數。Cobra 也內置了一些驗證函數：

• NoArgs：如果存在任何非選項參數，該命令將報錯。
• ArbitraryArgs：該命令將接受任何非選項參數。
• OnlyValidArgs：如果有任何非選項參數不在 Command 的 ValidArgs 字段中，該命令將報錯。
• MinimumNArgs(int)：如果沒有至少 N 個非選項參數，該命令將報錯。
• MaximumNArgs(int)：如果有多於 N 個非選項參數，該命令將報錯。
• ExactArgs(int)：如果非選項參數個數不為 N，該命令將報錯。
• ExactValidArgs(int)：如果非選項參數的個數不為 N，或者非選項參數不在 Command 的 ValidArgs 字段中，該命令將報錯。
• RangeArgs(min, max)：如果非選項參數的個數不在 min 和 max 之間，該命令將報錯。

使用預定義驗證函數，示例如下：

var cmd = &cobra.Command{
  Short: "hello",
  Args: cobra.MinimumNArgs(1), // 使用內置的驗證函數
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hello, World!")
  },
}

當然你也可以自定義驗證函數，示例如下：

var cmd = &cobra.Command{
  Short: "hello",
  // Args: cobra.MinimumNArgs(10), // 使用內置的驗證函數
  Args: func(cmd *cobra.Command, args []string) error { // 自定義驗證函數
    if len(args) < 1 {
      return errors.New("requires at least one arg")
    }
    if myapp.IsValidColor(args[0]) {
      return nil
    }
    return fmt.Errorf("invalid color specified: %s", args[0])
  },
  Run: func(cmd *cobra.Command, args []string) {
    fmt.Println("Hello, World!")
  },
}

4、PreRun and PostRun Hooks

在運行 Run 函數時，我們可以運行一些鈎子函數，比如 PersistentPreRun 和 PreRun 函數在 Run 函數之前執行，PersistentPostRun 和 PostRun 在 Run 函數之后執行。如果子命令沒有指定PersistentRun函數，則子命令將會繼承父命令的PersistentRun函數。這些函數的運行順序如下：

1、PersistentPreRun

2、PreRun

3、Run

4、PostRun

5、PersistentPostRun

注意，父級的 PreRun 只會在父級命令運行時調用，子命令是不會調用的。

Cobra 還支持很多其他有用的特性，比如：自定義 Help 命令；可以自動添加--version標志，輸出程序版本信息；當用戶提供無效標志或無效命令時，Cobra 可以打印出 usage 信息；當我們輸入的命令有誤時，Cobra 會根據注冊的命令，推算出可能的命令，等等。