go cli脚手架开发利器——cobra库的初体验

文章目录

    • 关于
    • 说明
      • cobra 简介
      • cobra 概念
      • Commands
      • Flags
      • Args
    • 教程正文
      • demo1 快速了解
        • demo
        • 知识点:Command创建命令
      • demo2 使用参数验证器、钩子函数
        • demo
        • 知识点:参数验证方法
        • 知识点:生命周期钩子函数
        • 知识点:帮助命令
        • 知识点:使用信息
      • demo3 生成帮助文档文件(markdown文件)
        • demo
        • 知识点 生成帮助文档文件(markdown文件)

关于

×错例:

  1. 不能完全代替shell,cobra能支持的脚本格式比较局限

  2. 无法像Java -jar -Dxx=str1 -Dxx2=str2 那样读取-D指示的值

  3. 读取参数只能为无格式纯文本,不要尝试读取json、特殊字符、转义符和富文本。

  4. 避免一大堆可变配置参数都通过flag传,参数太多建议改成读取配置文件

√正确:

  1. 读取5个以上的flag时使用,配置文件+viper,环境变量等,减少flag的个数到5个以内;

  2. 参数的值不要过长,仅纯文本string、int和bool类型,富文本、json等建议通过flag传文件路径,在run方法的逻辑读取文件,进行操作

  3. 短平快、小型脚手架推荐使用cobra封装命令集,同时学习了解pflag、flag、viper库

说明

cobra 简介

cobra既是一个用于创建强大现代CLI应用程序的库,也是一个生成应用程序和命令文件的程序。cobra被用在很多go语言的项目中,比如 Kubernetes、Docker、Istio、ETCD、Hugo、Github CLI等等,更多项目详见此列表。

cobra 概念

cobra由命令、参数、标志组成
commands代表动作,args是事物,flags是动作的修饰符(一般两个-连接符)
模式如下:
APPNAME VERB NOUN --ADJECTIVE. or APPNAME COMMAND ARG --FLAG(APPNAME 动词 名词 形容词 或者 APPNAME 命令 参数 标志)
如下的例子,server 是command,port是flag

hugo server --port=1313

Commands

命令是交互程序的中心,每一个命令都有子命令。
链接:cobra package - github.com/spf13/cobra - Go Packages
需要rootCmd和其他命令(按需)

Flags

flag是一种修改命令行为的方式,cobra支持完全兼容POSIX标志,也支持go flag package,cobra可以定义到子命令上的标志,也可以仅对该命令可用的标志

Args

args参数是命令command需要识别的一些值,cobra可以指定读取任意数量的参数,也可以不接受参数,此时该输入会被当作未定义的command报错。
command、args搭配使用

教程正文

demo1 快速了解

参考:Go语言命令行利器cobra使用教程 - 简书

demo

main.go负责调用rootCmd execute方法

import "cobra_cmd/cmd"

func main() {
    cmd.Execute()
}

在cmd目录下创建rootcmd.go

//每一个command命令,都是一个 &cobra.Command{
} 示例
var rootCmd = &cobra.Command{
    Use:   "root-cli",
    Short: "示例脚本 root cli",
    Long:  `这是 cobra 测试程序使用的示例脚本,您可参考cobra其他文档并随时更新本demo`,
         //参数验证器,设置某个脚本
能接受参数的个数。
    Args:  cobra.MinimumNArgs(1),
    RunE:  runRoot, //RunE Run字段都是执行具体的函数
,抽到别处定义
}
//rootCmd.Execute() 是命令执行入口
func Execute() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}
//具体的执行逻辑
func runRoot(cmd *cobra.Command, args []string) error {
    fmt.Printf("execute %s args:%v \n", cmd.Name(), args)
        //例如 这里处理无参数启动时程序处理
        if len(args) < 1 {
          return errors.New("requires at least one arg")
        }
     // do something.

    return nil

}

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("Print: " + strings.Join(args, " "))
    },
}

var cmdTimes = &cobra.Command{
    Use:   "times [# 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, " "))
        }
    },
}

 //定义 标志
var echoTimes int

func init() {
    //通过AddCommand组成父子关系,多级命令
    rootCmd.AddCommand(helloCmd)

    // root有两个子命令,和一个cmdEcho命令下的子命令cmdTimes
    //一级root --> 二级print,echo --> 三级times
    rootCmd.AddCommand(cmdPrint, cmdEcho)
    cmdEcho.AddCommand(cmdTimes)

    //本地标志,只在mdTimes命令

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

以上是一个入门demo,演示了命令command结构、标志的定义和读取、命令组成上下级、父子关系。

重点:
1.rootCmd和其他command放 cmd 包下;
2.在单独的commandXxx.go文件里,为每一个command定义 &cobra.Command{} 结构体并在init()方法里通过AddCommand() 做父子上下级关系关联、以及flag标志的读取操作;
3.main()入口方法调用到rootCmd.Execute()即完成工作。

知识点:Command创建命令

结构如下,列举大概常用的字段:

&cobra.Command{
        //
命令名称
    Use:   "echo [string to echo]",
        //
命令别名
    Aliases: []string{"log","output"},
        //
命令简介
    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("Print: " + strings.Join(args, " "))
    },
}
  • use 是该命令的用法,单行用法消息,表示了某一级命令,可以理解为该命令的名字;
  • Short、Long是该命令的一行简介、一大段详细介绍文本;具体会在输出help帮助时才有不一样的提示,可以粗暴设置成同样内容;
  • Run、RunE是命令被执行时的具体逻辑,RunE会返回error给上层;
  • Alias是一组可代替Use那个名字的,同名,都会映射到本命令;
  • Args:参数验证,可以限制参数的个数等等,有如图几种验证方法:
    go cli脚手架开发利器——cobra库的初体验_第1张图片

demo2 使用参数验证器、钩子函数

demo
package main

import (
    "bufio"
    "fmt"
    "github.com/spf13/cobra"
    "github.com/spf13/viper"
    "os"
)

var rootCmd = &cobra.Command{
    Use:   "demo",
    Short: "A brief description of your application",
    Long: `A longer description that spans multiple lines and likely contains
examples and usage of using your application. For example:

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.`,
    //运行命令的逻辑
    //Run: func(cmd *cobra.Command, args []string) {
    //debug
    //fmt.Println("== root命令运行成功 ==")

    //},

}

// 再定义二级子命令:
var createCmd = &cobra.Command{
    Use:   "create",
    Short: "创建书签",
}

var urlCmd = &cobra.Command{
    Use:   "url",
    Short: "Bookmark a url link ",
    Long:  "收藏一个url链接",

    //cobra 常用的参数配置校验器如下:
    //
    //MinimumNArgs(int) 当参数数目低于配置的最小参数个数时报错
    //MaximumNArgs(int) 当参数数目大于配置的最大参数个数时报错
    //ExactArgs(int)    如果参数数目不是配置的参数个数时报错
    //NoArgs            没有参数则报错

    //参数验证除了RangeArgs 还有 NoArg、ExactArgs、
    Args: cobra.RangeArgs(1, 3),

    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("link is:", link)
        if len(args) == 2 {
            fmt.Println(args[0], args[1])
        } else if len(args) == 0 {
            fmt.Println("收藏链接参数:", args)
            return
        } else {
            fmt.Println("收藏链接参数:", args)
        }
        file, err := os.OpenFile(filePath, os.O_WRONLY|os.O_CREATE, 0666)
        if err != nil {
            fmt.Println(err)
        }
        //及时关闭file句柄
        defer file.Close()
        //写入文件时,使用带缓存的 *Writer
        write := bufio.NewWriter(file)
        for i := 0; i < 5; i++ {
            write.WriteString("link \n")
        }
        //Flush将缓存的文件真正写入到文件中
        write.Flush()
    },

}
var link string
var filePath string

// init 方法完成父子关系绑定,标志的初始化设置以及其他初始化工作
func init() {
    rootCmd.AddCommand(createCmd)
    createCmd.AddCommand(urlCmd)
    //持久标志,传递给所有子命令
    rootCmd.PersistentFlags().StringVarP(&filePath, "path", "p", "./bookmarks.txt", "save to txt file")
    //局部标志,仅用于具体一个子命令
    urlCmd.Flags().StringVarP(&link, "link", "l", "", "收藏链接格式: 链接地址 名称")

    //钩子函数演示
    rootCmd.AddCommand(hookCmd)
    hookCmd.AddCommand(hookSub)
    hookSub.AddCommand(hookfinal)

}
func main() {

    // For environment variables.
    viper.SetEnvPrefix("core")
    viper.AutomaticEnv()
    if err := rootCmd.Execute(); err != nil {
        fmt.Println(err)
        os.Exit(1)
    }

}

// / 钩子函数测试
var hookCmd = &cobra.Command{
    Use:   "hookroot",
    Short: "钩子函数测试 一级",
    Long:  "测试 生命周期的不同钩子函数的继承关系",
    PersistentPreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookroot: PersistentPreRun")
    },
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookroot: PreRun")
    },
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookroot: Running...")
    },
    PostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookroot: PostRun")
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookroot: PersistentPostRun")
    },
}

// // 会继承 父命令的PersistentPreRun、PersistentPostRun
var hookSub = &cobra.Command{
    Use:   "hooksub",
    Short: "钩子函数测试 二级",
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hooksub: PreRun")
    },
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("hooksub: Running...")
    },
    PersistentPostRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hooksub: PersistentPostRun") //覆盖了root的PersistentPostRun,并传给下级
    },
}

// // 会继承 父命令的PersistentPreRun、PersistentPostRun
var hookfinal = &cobra.Command{
    Use:     "hookfinal",
    Aliases: []string{"final", "finally"},
    Short:   "钩子函数测试 三级",
    PreRun: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookfinal: PreRun")
    },
    Run: func(cmd *cobra.Command, args []string) {
        fmt.Println("hookfinal: Running...")
    },
}

output:
//go run .\helloworld.go hookroot hooksub hookfinal
//hookroot: PersistentPreRun
//hookfinal: PreRun
//hookfinal: Running...
//hooksub: PersistentPostRun/

以上是一个进阶demo,演示了PersistentFlags和Flags的区别,以及钩子函数在向下传递时可被覆盖

重点:
1.PersistentFlags 设置的是持久标志,由rootCmd根命令设置,可被其他命令使用,而flag设置的只能在当前命令使用;
2.在单独的command执行之前、之后都可以执行其他操作,也即预先处理、后置处理。执行顺序为PersistentPreRun、PreRun、Run、PostRun、PersistentPostRun
3.带Persistent的可以传递给子命令(继承),但也可以被子命令重新声明而被覆盖(重写)
4.不带Persistent开头的前后处理

知识点:参数验证方法

以下代码:Args: cobra.MinimumNArgs(1)就是一个验证方法

import (
  "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
  Use:   "myapp",
  Short: "A brief description of your application",
  Long:  `A longer description that spans multiple lines and likely contains examples and usage of using your application.`,
  Args: cobra.MinimumNArgs(1),
  Run: func(cmd *cobra.Command, args []string) {
    // Do something here
  },
}

func init() {
  // Here you will define your flags and configuration settings.
}

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

可以看到在 rootCmd 中设置了 Args: cobra.MinimumNArgs(1),这将强制要求至少传入一个参数,否则会抛出一个错误。此外,还可以使用 cobra 提供的其他参数验证方法,例如:

cobra.MaximumNArgs(n int):强制要求不超过 n 个参数。
cobra.OnlyValidArgs([]string):强制要求传入的参数必须是所指定的 string 类型的 slice 中的值。
cobra.ArgRange(min, max int):强制要求传入参数的数量在 min 和 max 之间。
以上是一些常用的参数验证方法,Cobra 还有更多的验证方法和选项,可以根据实际需求进行选择和设置。

知识点:生命周期钩子函数

参考:
Go 每日一库之 cobra - 知乎
Cobra 中文文档 - 掘金

可以在执行命令之前和之后运行一个函数。PersistentPreRun 和 PreRun 函数将在 Run 之前执行。PersistentPostRun 和 PostRun 会在 Run 之后运行。如果子级未声明自己的 Persistent * Run 函数,则子级将继承父级的。这些函数的执行顺续如下:

PersistentPreRun
PreRun
Run
PostRun
PersistentPostRun
PersistentXxx是可以被子命令继承的前、后置处理

知识点:帮助命令

当你添加了子命令,Cobra 会自动添加一些帮助命令。当你执行 app help 命令时会显示帮助信息。另外,help 还支持其他命令作为输入参数。举例来说,你有一个没有额外配置的 create 命令,app help create 是有效的。每一个命令还会自动获取一个 --help 标志。

help 就像其他命令一样。并没有特殊的逻辑或行为。实际上,你可以根据需要提供自己的服务。
定义你自己的 help
你可以使用下面的方法提供你自己的 Help 命令或模板。

cmd.SetHelpCommand(cmd *Command)
cmd.setHelpCommand(f func(*Command, []string))
cmd.setHelpTemplate(s string)

后两者也适用于所有子命令。

知识点:使用信息

当用户提供无效的标志或无效的命令时,Cobra 会通过向用户显示 usage 进行响应。
这时可以自定义usage用法,提供自己的 usage函数和模板

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

可以参考 GitHub CLI 项目中usage使用信息的写法。

demo3 生成帮助文档文件(markdown文件)

参考cobra document#mrkdown-docs
cobra支持生成所有命令的帮助文档树doc.GenMarkdownTree(cmd,dir)

demo

main.go:

import (
	"github.com/spf13/cobra/doc"
	"log"
	"os"
)

func InitCommand() {
	rootCmd.AddCommand(helloCmd)
	// 两个顶层的命令,和一个cmdEcho命令下的子命令cmdTimes
	rootCmd.AddCommand(cmdPrint, cmdEcho)
	cmdEcho.AddCommand(cmdTimes)
	//utils.Mkdir("./docs")
	os.MkdirAll("H:\\docs", os.ModePerm) //显式创建目标文件夹,文件夹存在时再次调用不会做任何事情
	err := doc.GenMarkdownTree(rootCmd, "H:\\docs") //核心api  GenMarkdownTree
	if err != nil {
		log.Fatal(err)
	}
}
知识点 生成帮助文档文件(markdown文件)

给某个命令及其子命令生成帮助文档树(一系列文档),参考以下代码片段:

err := doc.GenMarkdownTree(rootCmd, "H:\\docs") //核心api  GenMarkdownTree
	if err != nil {
		log.Fatal(err)
	}

即可在目标文件夹下看到生成的md文件:
go cli脚手架开发利器——cobra库的初体验_第2张图片

其他高级用法或生成其他格式帮助文档,请参考cobra document#mrkdown-docs ,以及cobra代码库的github.com/spf13/cobra/doc文件夹下的代码和文档。

go cli脚手架开发利器——cobra库的初体验_第3张图片

你可能感兴趣的:(go知识,感悟,golang,开发语言,后端)