【项目开发】Cobra 命令与参数

---

我的随笔录：Satori2Core 随笔录 —— 更新计划 / 笔录目录 (opens new window)

代码示例地址 (opens new window)

---

Cobra 命令与参数

1. 基本认识

在 Cobra 中，​命令代表一个可执行的操作（如 create），而参数​(Flags)则是命令的配置选项（如 -n 或 --name）。参数可以修改命令的行为，实现动态功能调整。

比如如果我们的项目有多个版本的配置文件，则可以通过参数来基于哪一个配置文件启动服务。

---

1.1 参数是什么？

• 本质​：命令的可选配置项
• ​作用​：调整命令行为，传递额外信息
• ​特点​：
  • 以 - 或 -- 开头（如 -n，--name）
  • 不属于命令名的一部分
  • 不影响命令层级结构

---

1.2 为什么需要参数？

场景示例​：文件复制工具

基础命令：copy

但当需要实现：

• 覆盖已存在文件时 → 需要 --force
• 保留文件属性时 → 需要 --preserve
• 仅复制更新文件时 → 需要 --update

# 无参数版本（功能有限）
copy source.txt target.txt

# 带参数版本（功能强大）
copy --force --update source.txt target.txt

---

2. 参数类型与解析方法认识

类型	作用域	创建方法	使用场景
本地参数	仅当前命令	Flags()	命令特有的配置（如 create -n file.txt）
持久参数	该命令及其所有子命令	PersistentFlags()	全局配置（如 --verbose 调试模式）

---

【解析方法的使用格式】

• cmd.Flags().类型P(长名称, 短名称, 默认值, 帮助文本)
• 参数说明：
  • StringP: - P代表支持短/长两种形式
  • "text" -> 长参数：--text
  • "t" -> 短参数：-t
  • "Hello" -> 默认值（用户不指定时使用）

---

3. 命令参数的简单认识与使用

3.1 示例代码

func main() {
	// 根命令
	rootCmd := &cobra.Command{
		Use:   "repeat",
		Short: "重复输出文本",

		// 参数绑定后自动注入
		Run: func(cmd *cobra.Command, args []string) {
			// 获取参数值（从 cmd.Flags()）
			text, _ := cmd.Flags().GetString("text")
			count, _ := cmd.Flags().GetInt("count")

			// 核心业务逻辑
			result := strings.Repeat(text+" ", count)
			fmt.Println("输出", strings.TrimSpace(result))
		},
	}

	// 添加文本参数（支持长/短两种模式）
	rootCmd.Flags().StringP("text", "t", "Hello", "要重复的文本")

	// 添加次数参数
	rootCmd.Flags().IntP("count", "c", 3, "重复次数")

	rootCmd.Execute()
}

3.2 使用演示

# 示例：开始 -----------------------------------------------------------------------------
➜  cobra-flags git:(learn/cobra) ✗ go build -o repeat         # 编译
➜  cobra-flags git:(learn/cobra) ✗ ./repeat                   # 使用默认参数（默认文本：Hello；默认重复次数：3）
输出 Hello Hello Hello                                        
➜  cobra-flags git:(learn/cobra) ✗ ./repeat --text=World      # 指定文本
输出 World World World
➜  cobra-flags git:(learn/cobra) ✗ ./repeat -t Golang -c 2    # 混合使用短参数
输出 Golang Golang
➜  cobra-flags git:(learn/cobra) ✗ ./repeat -h                # 帮助信息（自动包含参数说明）
重复输出文本

Usage:
  repeat [flags]

Flags:
  -c, --count int     重复次数 (default 3)
  -h, --help          help for repeat
  -t, --text string   要重复的文本 (default "Hello")
➜  cobra-flags git:(learn/cobra) ✗ 
# 示例：结束 -----------------------------------------------------------------------------

---

4. 参数类型及使用示例

4.1 多类型参数使用

类型	创建方法	获取方法	用途示例
字符串	StringP()	GetString()	文件名、文本内容
整数	IntP()	GetInt()	重复次数、端口号
布尔值	BoolP()	GetBool()	开关选项（true/false）
时间	DurationP()	GetDuration()	超时设置
字符串数组	StringSliceP()	GetStringSlice()	文件列表

---

4.2 示例：增强版文件检测工具

【代码示例】

func main() {
	rootCmd := &cobra.Command{
		Use:   "filecheck",
		Short: "文件检查工具",
		Run: func(cmd *cobra.Command, args []string) {
			// 获取所有参数
			path, _ := cmd.Flags().GetString("path")
			recursive, _ := cmd.Flags().GetBool("recursive") // 是否启用递归模式
			minSize, _ := cmd.Flags().GetInt64("min-size")
			exts, _ := cmd.Flags().GetStringSlice("ext")

			fmt.Printf("检查路径: %s\n", path)
			fmt.Printf("递归模式: %v\n", recursive)
			fmt.Printf("最小尺寸: %d字节\n", minSize)
			fmt.Printf("扩展名过滤: %v\n", exts)
		},
	}

	// 支持不同数据类型
	rootCmd.Flags().StringP("path", "p", ".", "检查路径")
	rootCmd.Flags().BoolP("recursive", "r", false, "递归检查")
	rootCmd.Flags().Int64P("min-size", "s", 1024, "最小文件大小（字节）")
	rootCmd.Flags().StringSliceP("ext", "e", []string{}, "按扩展名过滤（可多个）")

	rootCmd.Execute()
}

---

【使用示例】

# 示例：开始 -----------------------------------------------------------------------------
➜  filecheck git:(learn/cobra) ✗ go build -o filecheck
➜  filecheck git:(learn/cobra) ✗ ./filecheck -p /data -r -s 2048 -e jpg -e png
检查路径: /data
递归模式: true
最小尺寸: 2048字节
扩展名过滤: [jpg png]
➜  filecheck git:(learn/cobra) ✗ 
# 示例：结束 -----------------------------------------------------------------------------

---

5. 关键参数功能 —— 特殊情景

5.1 必填参数

• 先添加参数，再对这个参数标记为必填！（不指定即非必填）

• 关键方法：MarkFlagFlagRequired("需要必填的字段名")

// 添加参数后标记为：必填
func main() {
	rootCmd := &cobra.Command{
		Use:   "sptest",
		Short: "特殊场景测试",
		Run: func(cmd *cobra.Command, args []string) {
			username, _ := cmd.Flags().GetString("username")

			fmt.Printf("用户输入的用户名是：%s\n", username)
		},
	}

	rootCmd.Flags().StringP("username", "u", "匿名", "用户名（必须）")
	rootCmd.MarkFlagRequired("username")    // 关键方法

	rootCmd.Execute()
}

// 效果：
// 当用户忘记输入时自动报错
// Error: required flag "username" not set

---

5.2 参数关联验证

• 参数关联验证，即有的参数需要依赖于其他参数是合法的！
• 关键方法：PreRun

func main() {
	rootCmd := &cobra.Command{
		Use:   "sptest",
		Short: "特殊场景测试",
		Run: func(cmd *cobra.Command, args []string) {
			output, _ := cmd.Flags().GetString("output")
			theme, _ := cmd.Flags().GetString("theme")

			fmt.Println("输出：", output)
			fmt.Println("主题：", theme)
		},
	}

	rootCmd.Flags().StringP("output", "o", "text", "输出格式")
	rootCmd.Flags().StringP("theme", "t", "light", "颜色主题")

	// 参数验证（定义在Run函数前）
	rootCmd.PreRun = func(cmd *cobra.Command, args []string) {
		output, _ := cmd.Flags().GetString("output")
		if output != "text" && output != "json" {
			log.Fatal("输出格式必须是text或json")
		}
	}
	rootCmd.Execute()
}

/*
测试：

➜  special git:(learn/cobra) ✗ go build -o sptest
➜  special git:(learn/cobra) ✗ ./sptest -o png -t night
2025/06/22 22:28:22 输出格式必须是text或json
*/

---

6. 参数使用流程图

---