現代化的命令列框架：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 會根據註冊的命令，推算出可能的命令，等等。