Cobra框架使用手冊

尹瑞星發表於2021-07-07

cobra框架使用手冊

cobra是go語言的一個庫，可以用於編寫命令列工具。

概念

Cobra 結構由三部分組成：命令 (commands)、引數 (arguments)、標誌 (flags)。最好的應用程式在使用時讀起來像句子，要遵循的模式是APPNAME VERB NOUN --ADJECTIVE。

安裝

此命令將安裝cobra生成器可執行檔案以及庫及其依賴項：

go get -u github.com/spf13/cobra
#接下來匯入
import "github.com/spf13/cobra"

使用Cobra生成器

這是將Cobra合併到應用程式最簡單的方法。

#首先編譯cobra命令,將在$GOPATH/bin下建立cobra的可執行檔案
go get github.com/spf13/cobra/cobra

cobra init [app]

建立初始應用程式程式碼，用正確的結構填充應用程式，可以立即享受cobra的好處，還會自動將您指定的許可證應用於您的應用程式。

可以在當前目錄中執行，也可在指定現有專案的相對路徑，如果目錄不存在，將會建立。

#注意：非空目錄上執行將不在失敗，--pkg-name是必須的
mkdir -p newApp && cd newApp
cobra init --pkg-name github.com/spf13/newApp

cobra init --pkg-name github.com/spf13/newApp path/to/newApp

cobra add

一旦應用程式初始化後，cobra就可以為您建立其他命令，假設需要如下命令：

app server
app config
app config create

在專案根目錄下（mian.go所在的目錄）執行

cobra add server
cobra add config
cobra add create -p 'configCmd'

注意：使用camelCase（not snake_case/kebab-case）命名

然後將會看到類似下面的程式結構：

  ▾ app/
    ▾ cmd/
        serve.go
        config.go
        create.go
      main.go

此時執行go run main.go、go run main.go serve/config/config create/help serve等都會工作。

顯然，您還沒有將自己的程式碼新增到這些中，命令就已經準備就緒。

配置Cobra生成器：

如果提供一個簡單的配置檔案，那麼Cobra生成器將更易於使用。

示例配置~/.cobra.yaml：

author: Steve Francia <spf@spf13.com>
license: MIT

還可以使用內建許可證，還可以通過設定license為none來指定無許可證或者指定一個自定義許可證。

author: Steve Francia <spf@spf13.com>
year: 2020
license:
  header: This file is part of CLI application foo.
  text: |
    {{ .copyright }}

    This is my license. There are many like it, but this one is mine.
    My license is my best friend. It is my life. I must master it as I must
    master my life.

LICENSE檔案的內容為：

Copyright © 2020 Steve Francia <spf@spf13.com>

This is my license. There are many like it, but this one is mine.
My license is my best friend. It is my life. I must master it as I must
master my life.

使用Cobra庫

要手動實現Cobra，需要建立一個mian.go檔案和rootCmd檔案。

建立 rootCmd

Cobra不需要任何特殊的構造器。只需建立命令。

place this file in app/cmd/root.go

var rootCmd = &cobra.Command{
  Use:   "hugo",
  Short: "Hugo is a very fast static site generator",
  Long: `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`,
  Run: func(cmd *cobra.Command, args []string) {
    // Do Stuff Here
  },
}

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

還可以在init()函式中定義標誌和控制程式碼配置：

package cmd

import (
	"fmt"
	"os"

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

var (
	// Used for flags.
	cfgFile     string
	userLicense string

	rootCmd = &cobra.Command{
		Use:   "cobra",
		Short: "A generator for Cobra based Applications",
		Long: `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.`,
	}
)

// Execute executes the root command.
func Execute() error {
	return rootCmd.Execute()
}

func init() {
	cobra.OnInitialize(initConfig)

	rootCmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.cobra.yaml)")
	rootCmd.PersistentFlags().StringP("author", "a", "YOUR NAME", "author name for copyright attribution")
	rootCmd.PersistentFlags().StringVarP(&userLicense, "license", "l", "", "name of license for the project")
	rootCmd.PersistentFlags().Bool("viper", true, "use Viper for configuration")
	viper.BindPFlag("author", rootCmd.PersistentFlags().Lookup("author"))
	viper.BindPFlag("useViper", rootCmd.PersistentFlags().Lookup("viper"))
	viper.SetDefault("author", "NAME HERE <EMAIL ADDRESS>")
	viper.SetDefault("license", "apache")

	rootCmd.AddCommand(addCmd)
	rootCmd.AddCommand(initCmd)
}

func initConfig() {
	if cfgFile != "" {
		// Use config file from the flag.
		viper.SetConfigFile(cfgFile)
	} else {
		// Find home directory.
		home, err := os.UserHomeDir()
		cobra.CheckErr(err)

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

	viper.AutomaticEnv()

	if err := viper.ReadInConfig(); err == nil {
		fmt.Println("Using config file:", viper.ConfigFileUsed())
	}
}

建立 main.go

main.go也很簡單，只有一個目標：初始化cobra

package main

import (
  "{pathToYourApp}/cmd"
)

func main() {
  cmd.Execute()
}

建立其他命令

通常每個命令在cmd/目錄下都有自己的檔案，如果要建立版本命令，可以建立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")
  },
}

返回和處理錯誤

如果你希望返回一個錯誤給命令的呼叫者，可以使用RunE。

package cmd

import (
  "fmt"

  "github.com/spf13/cobra"
)

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

var tryCmd = &cobra.Command{
  Use:   "try",
  Short: "Try and possibly fail at something",
  RunE: func(cmd *cobra.Command, args []string) error {
    if err := someFunc(); err != nil {
	return err
    }
    return nil
  },
}

可以在execute函式呼叫中捕獲錯誤。

使用標誌

標誌提供修飾符來控制操作命令的操作方式。

為命令指定flags

由於標誌是在不同的位置定義和使用的，因此我們需要在外部定義一個具有正確作用域的變數來分配要使用的標誌。

var Verbose bool
var Source string

持久標誌：該標誌可用於分配給它的命令以及該命令下的每個命令。
```
rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")
```

區域性標誌：只適用於特定命令。

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

父命令上的本地標誌：

預設情況下，Cobra只解析目標命令上的區域性標誌，而忽略父命令上的任何區域性標誌。

command := cobra.Command{
  Use: "print [OPTIONS] [COMMANDS]",
  TraverseChildren: true,
}

用配置繫結標誌：

使用viper繫結flags

var author string

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

注意：當使用者未提供--author標誌時，變數author將不會設定為config中的值。

必須標誌：

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

rootCmd.PersistentFlags().StringVarP(&Region, "region", "r", "", "AWS region (required)")
rootCmd.MarkPersistentFlagRequired("region")

位置引數和自定義引數：

可以使用命令的Args欄位指定位置引數

var cmd = &cobra.Command{
  Short: "hello",
  Args: func(cmd *cobra.Command, args []string) error {
    if len(args) < 1 {
      return errors.New("requires a color argument")
    }
    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!")
  },
}

示例

在下面的示例中，我們定義了三個命令。兩個是頂級命令，一個（cmdTimes）是頂級命令之一的子命令。在這種情況下，根是不可執行的，這意味著需要一個子命令。這是通過不為“rootCmd”提供“Run”來實現的。

我們只為一個命令定義了一個標誌。

package main

import (
  "fmt"
  "strings"

  "github.com/spf13/cobra"
)

func main() {
  var echoTimes int

  var cmdPrint = &cobra.Command{
    Use:   "print [string to print]",
    Short: "Print anything to the screen",
    Long: `print is for printing anything back to the screen.
For many years people have printed back to the screen.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Print: " + strings.Join(args, " "))
    },
  }

  var cmdEcho = &cobra.Command{
    Use:   "echo [string to echo]",
    Short: "Echo anything to the screen",
    Long: `echo is for echoing anything back.
Echo works a lot like print, except it has a child command.`,
    Args: cobra.MinimumNArgs(1),
    Run: func(cmd *cobra.Command, args []string) {
      fmt.Println("Echo: " + strings.Join(args, " "))
    },
  }

  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, " "))
      }
    },
  }

  cmdTimes.Flags().IntVarP(&echoTimes, "times", "t", 1, "times to echo the input")

  var rootCmd = &cobra.Command{Use: "app"}
  rootCmd.AddCommand(cmdPrint, cmdEcho)
  cmdEcho.AddCommand(cmdTimes)
  rootCmd.Execute()
}

Help Cmmand

當您有子命令時，Cobra會自動將help命令新增到應用程式中。當使用者執行app help時，將呼叫此函式。此外，help還支援所有其他命令作為輸入。例如，您有一個名為“create”的命令，沒有任何附加配置；呼叫“app help create”時，Cobra將起作用。每個命令都會自動新增“-help”標誌。

自定義help命令和模版

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

Useage Message

當使用者提供無效標誌或無效命令時，Cobra會通過向使用者顯示“usage”（使用情況）來響應。

自定義useage

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

參考連結：

https://github.com/spf13/cobra/blob/master/user_guide.md

WebApiThrottle限流框架使用手冊
2015-07-21
WebAPI框架
Linux使用手冊-vi使用手冊
2014-11-27
Linux
validation客戶端驗證框架使用手冊
2020-12-12
客戶端框架
TcpDump使用手冊
2020-08-19
TCP
MyBatis 使用手冊
2020-11-21
MyBatis
sqlmap使用手冊
2022-03-04
SQL
Mybatis應用手冊
2023-03-26
MyBatis
Tmux使用手冊
2017-10-10
UX
Docker使用手冊
2017-12-13
Docker
Promise使用手冊
2017-04-19
Promise
Redis使用手冊
2014-08-18
Redis
iptables 使用手冊
2010-12-02
DotProject 使用手冊
2011-11-08
Project
Koa框架教程,Koa框架開發指南,Koa框架中文使用手冊,Koa框架中文文件
2017-08-09
框架
git 基本使用手冊
2020-07-06
Git
Memcached Client 使用手冊
2013-10-29
client
jQuery使用手冊（收藏）
2007-04-19
jQuery
儀器使用手冊
2024-03-22
PerfDog WEB端使用手冊
2020-08-04
Web
【C#】CsvHelper 使用手冊
2020-05-20
C#
Room Database完全使用手冊
2019-01-18
OOMDatabase
MongoDB和pymongo自用手冊
2018-09-14
MongoDB
Git 快速使用手冊（二）
2020-12-08
Git
less語法實用手冊
2017-11-23
Linux iptables應用手冊
2008-06-23
Linux
gcc使用手冊(2)(轉)
2007-08-11
GC
gcc使用手冊(3)(轉)
2007-08-11
GC
gcc使用手冊(4)(轉)
2007-08-11
GC
《Redis 使用手冊》- 字串（PHP 版本）
2019-12-24
Redis字串PHP
MySQL DBA 常用手冊小結
2021-09-09
MySql
ThreadLocal 使用手冊 | 按需收藏
2023-01-12
thread
Linux parallel 命令使用手冊
2023-04-10
LinuxParallel
BeautifulSoup使用手冊（查詢篇）
2020-10-03
Kotlin 協程使用手冊
2018-02-24
Kotlin
Gerrit和Jenkins使用手冊
2018-04-24
Jenkins
MySQL DBA常用手冊小結
2016-04-18
MySql
AutoMapper使用手冊(一)
2015-02-14
APP
【C#】AutoMapper 使用手冊
2020-06-12
C#APP