簡介

Star：26.5K

Cobra是一個用Go語言實現的命令列工具。並且現在正在被很多專案使用，例如：Kubernetes、Hugo和Github CLI等。通過使用Cobra，我們可以快速的建立命令列工具，特別適合寫測試指令碼，各種服務的Admin CLI等。

比如 Mattermost 專案，就寫了很多 Admin CLI：

為什麼需要cobra

我們看一個簡單的demo

使用前

package main
 
import (
    "flag"
    "fmt"
)
 
func main() {
    flag.Parse()
 
    args := flag.Args()
    if len(args) <= 0 {
        fmt.Println("Usage:  admin-cli [command]")
        return
    }
 
    switch args[0] {
    case "help":
        // ...
    case "export":
        //...
        if len(args) == 3 { // 匯出到檔案
            // todo
        } else if len(args) == 2 { // 匯出...
            // todo
        }
    default:
        //...
    }
}

使用後

package main
 
import (
    "fmt"
    "github.com/spf13/cobra"
    "os"
)
 
// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
    Use:   "api",
    Short: "A brief description of your application",
    Long:  `A longer description `,
}
 
// 命令一
var mockMsgCmd = &cobra.Command{
    Use:   "mockMsg",
    Short: "批次傳送測試文字訊息",
    Long:  ``,
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("mockMsg called")
    },
}
 
// 命令二
var exportCmd = &cobra.Command{
    Use:   "export",
    Short: "匯出資料",
    Long:  ``,
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("export called")
    },
}
 
func Execute() {
    err := rootCmd.Execute()
    if err != nil {
        os.Exit(1)
    }
}
 
func init() {
    rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
 
    rootCmd.AddCommand(mockMsgCmd)
    rootCmd.AddCommand(exportCmd)
 
    exportCmd.Flags().StringP("out", "k", "./backup", "匯出路徑")
}
 
func main() {
    Execute()
}

執行：

$ go run main.go
A longer description
 
Usage:
  api [command]
 
Available Commands:
  completion  Generate the autocompletion script for the specified shell
  export      匯出資料
  help        Help about any command
  mockMsg     批次傳送測試文字訊息
 
Flags:
  -h, --help     help for api
  -t, --toggle   Help message for toggle
 
Use "api [command] --help" for more information about a command.

發現了嗎？你不用再處理各種引數組合了，從此釋放了出來，只需要寫自己的業務邏輯即可！

基本概念

Cobra由三部分組成：

命令(Commands )：代表行為。命令是程式的中心點，程式的每個功能都應該可以通過命令進行互動，一個命令可以有任意個子命令。
引數(Args)：命令的引數
標誌(Flags)：修飾命令。它修飾命令該如何完成。

官方推薦命令格式為：

$ ./appName command args --Flag

如 hugo server --port=1313 ：

appName: hugo
command: server
flag: port

安裝

Go pkg

新增依賴

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

匯入即可：

import "github.com/spf13/cobra"

命令列工具

建議安裝命令列工具 `cobra-cli` ，以方便快速建立cobra專案，增加command等。

# 命令列工具
$ go install github.com/spf13/cobra-cli@latest

安裝完成之後，執行 `cobra-cli --help` （請確保GOBIN已設定），輸出下列資訊則代表成功：

$ cobra-cli --help
Cobra is a CLI library for Go that empowers applications.
This application is a tool to generate the needed files
to quickly create a Cobra application.
 
Usage:
  cobra-cli [command]
 
Available Commands:
  add         Add a command to a Cobra Application
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  init        Initialize a Cobra Application
 
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 cobra-cli
  -l, --license string   name of license for the project
      --viper            use Viper for configuration
 
Use "cobra-cli [command] --help" for more information about a command.

入門實踐

新建cobra命令列程式

安裝了cobra-cli工具之後，執行 init 初始化建立專案：

$ cobra-cli init

此時，在當前目錄自動生成如下檔案：

├── LICENSE
├── cmd
│   └── root.go
└── main.go

main.go：

package main
 
import "tools/api/cmd"
 
func main() {
   cmd.Execute()
}

root.go（有刪減）：

package cmd
 
import (
   "fmt"
 
   "github.com/spf13/cobra"
)
 
// rootCmd represents the base command when called without any subcommands
var rootCmd = &cobra.Command{
   Use:   "api",
   Short: "A brief description of your application",
   Long:  `A longer description `,
   //Run: func(cmd *cobra.Command, args []string) {
   // fmt.Println("api called")
   //},
}
 
// Execute adds all child commands to the root command and sets flags appropriately.
// This is called by main.main(). It only needs to happen once to the rootCmd.
func Execute() {
   err := rootCmd.Execute()
   if err != nil {
      os.Exit(1)
   }
}
 
func init() {
   // 全域性flag
   // rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.api.yaml)")
 
   // local flag，暫不知道用處
   rootCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
}

此時執行，不用指定引數，會執行rootCmd，列印使用說明：

$ go build 
$ ./api

輸出：

A longer description
 
Usage:
  api [command]
 
Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
 
Flags:
  -h, --help     help for api
  -t, --toggle   Help message for toggle
 
Use "api [command] --help" for more information about a command.

命令構成

分析上面的預設輸出：

Available Commands：代表可以執行的命令。比如./api connect
Flags：是引數。比如./api connect --ip=127.0.0.1:6379，--ip就是flag，127.0.0.1:6379就是flag的值。

新增命令

我們來新增一個命令試試，這也是命令列程式的魅力，通過不同的引數執行不同的動作。

語法：

$ cobra-cli add [command]

比如：

$ cobra-cli add mock-msg
mockMsg created at /Users/xxx/repo/tools/api

此時，在cmd下會多一個檔案（mock_msg.go），內容如下：

package cmd
 
import (
   "fmt"
 
   "github.com/spf13/cobra"
)
 
var mockMsgCmd = &cobra.Command{
   Use:   "mockMsg",
   Short: "A brief description of your command",
   Long: `mock msg command`,
   Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("mockMsg called")
   },
}
 
func init() {
   rootCmd.AddCommand(mockMsgCmd)
}

再執行rootCmd：

$ go build
$ ./api

會發現，多了一個命令：

// ...
Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  mockMsg     A brief description of your command
// ...

執行mocMsg命令：

$ ./api mockMsg
 
mockMsg called

此時，就可以在生成的 mock_msg.go: Run() 函數中，放你自己的業務邏輯程式碼了。

如何顯示自己的命令用法

上面新增了一個命令mockMsg，通過 ./api help 列印了命令和help，但是 `Use` 裡面指定的內容列印到哪裡去了呢？

這個時候，需要針對Command在指定help，此時就能列印這個命令的具體用法了。

./api mockMsg help
批次生產mq訊息
 
Usage:
  benchmark mockmsg [flags]
 
Flags:
  -g, --goroutine int32   並行routine數量 (default 1)
  -h, --help              help for mockmsg
  -p, --packet int32      每個routine一秒寫入mq的數量 (default 20)


-g和-p是新增的2個flag：

func init() {
   mockmsgCmd.Flags().Int32P("goroutine", "g", 1, "並行routine數量")
   mockmsgCmd.Flags().Int32P("packet", "p", 20, "每個routine一秒寫入mq的數量")
 
   rootCmd.AddCommand(mockmsgCmd)
}

獲取這2個值：

// mockmsgCmd represents the mockmsg command
var mockmsgCmd = &cobra.Command{
   Use:   "mockmsg",
   Short: "批次生產mq訊息",
   Run: func(cmd *cobra.Command, args []string) {
      // 這裡要寫全名
      g, _ := cmd.Flags().GetInt32("goroutine")
      p, _ := cmd.Flags().GetInt32("packet")
      fmt.Println("mockmsg called,flags:g=", g, ",p=", p, ",args:", args)
   },
}

執行：

$ go run main.go mockmsg -p 322 -g 5 args1 args2
mockmsg called,flags:g= 5 ,p= 322 ,args: [args1 args2]

總結

我們通過一個例子，介紹了使用cobra帶來的好處。通過一個完整的入門實踐，演示了建立專案、新增命令和使用的一些範例，希望對你有所幫助！

參考：

go Cobra命令列工具入門

簡介