Go Cobra 怎样给位置参数设置数量范围

如果一个 Cobra 子命令只接受 1 到 3 个位置参数，最直接的写法是把 cobra.RangeArgs(1, 3) 赋给命令的 Args 字段。这样数量检查发生在 RunE 之前，参数不合规时不会先打开文件、连接服务或执行其他副作用。

官方地址：https://github.com/spf13/cobra/

位置参数的数量约束放在 Command.Args：固定数量用 ExactArgs，只设一侧边界用 MinimumNArgs 或 MaximumNArgs，同时设置上下界用 RangeArgs。

用 Args 把数量边界交给 Cobra

下面的命令允许用户传入一个到三个文件名。RangeArgs 的上下界都是包含关系，因此 1、2、3 个位置参数合法，0 个或超过 3 个都会在进入业务函数前返回错误。

package main

import (
	"fmt"

	"github.com/spf13/cobra"
)

var copyCmd = &cobra.Command{
	Use:   "copy  [target...]",
	Short: "复制一到三个文件",
	// 先校验位置参数数量，避免 RunE 产生文件或网络副作用。
	Args: cobra.RangeArgs(1, 3),
	RunE: func(cmd *cobra.Command, args []string) error {
		// Args 已经通过数量校验，这里只处理业务逻辑。
		fmt.Printf("收到 %d 个位置参数\\n", len(args))
		return nil
	},
}

func main() {
	rootCmd := &cobra.Command{Use: "filetool"}
	rootCmd.AddCommand(copyCmd)
	// Execute 会在 RunE 前调用 Args 校验器。
	if err := rootCmd.Execute(); err != nil {
		// 统一返回错误，避免把非法参数当成正常任务处理。
		fmt.Println(err)
	}
}

这里的关键不是在 RunE 里再次判断 len(args)，而是让命令声明本身拥有参数契约。Use 负责帮助信息中的形态提示，Args 负责可执行性检查，两者应该保持一致。

四种内置校验器怎样选择

不同命令的边界可以直接映射到 Cobra 的内置函数：

例如只允许一个输入文件时用 ExactArgs(1)；批量命令至少要有一个资源名时用 MinimumNArgs(1)。不要把 ValidArgs 当成数量限制，它描述的是补全或允许的参数值；数量与值是两种不同约束。

数量校验与内容校验怎样组合

当命令既要求参数数量，又要求参数来自固定集合，可以用 MatchAll 合并规则。下面的示例允许传入 1 到 2 个环境名，并要求这些值出现在 ValidArgs 中：

var deployCmd = &cobra.Command{
	Use:       "deploy ...",
	Short:     "部署到指定环境",
	ValidArgs: []string{"dev", "staging", "prod"},
	// 一个校验数量，一个校验值域，二者都通过才进入 RunE。
	Args: cobra.MatchAll(
		cobra.RangeArgs(1, 2),
		cobra.OnlyValidArgs,
	),
	RunE: func(cmd *cobra.Command, args []string) error {
		// 这里可以安全地使用已通过边界检查的环境列表。
		return deploy(args)
	},
}

如果还要检查文件扩展名、参数之间的依赖关系或互斥语义，可以实现 func(cmd *cobra.Command, args []string) error 形式的自定义校验器。建议先调用内置校验器，再补充自己的规则，让错误职责保持清楚。

不要把 flag 和位置参数混在一起计算

--region cn 这类命令行选项属于 flag，不是传给 Args 校验器的普通位置参数。数量规则要围绕真正的资源名、文件名或环境名设计；如果读者看到的是选项数量，应该改用 Cobra 的 flag 约束或标记 API。

实际落地时至少覆盖 0、1、3、4 个位置参数四个边界：0 个和 4 个应被拒绝，1 个和 3 个应通过；再单独测试带 flag 的调用，确认 flag 不会改变位置参数计数。这样可以避免把数量检查藏在业务函数中，造成非法输入已经触发副作用的问题。

常见疑问

RangeArgs 的 max 是否包含在允许范围内？

包含。RangeArgs(min, max) 表示数量落在 min 到 max 的闭区间内，边界值应按合法输入测试。

为什么不直接在 RunE 里判断 len(args)？

把约束放在 Args 更符合 Cobra 的命令生命周期：校验失败会在业务执行前返回，也能复用内置错误与使用提示。只有当规则涉及参数内容或参数之间的关系时，才需要补充自定义校验。

小结：固定数量选 ExactArgs，单侧边界选 MinimumNArgs 或 MaximumNArgs，闭区间选 RangeArgs；数量与值域同时存在时用 MatchAll。把这些规则放在 Command.Args，命令的声明、帮助信息和业务执行边界就能保持一致。