Go flag.BoolFunc 怎样处理重复出现的布尔开关

如果一个命令行选项的语义是“每出现一次就执行一次动作”，而不是“最后得到一个 true 或 false”，可以优先考虑 flag.FlagSet.BoolFunc。它不要求开关后面跟值；解析器每遇到一次该开关，就把对应的字符串值交给回调。于是 -verbose -verbose 可以自然地表示两次启用，而不需要另外维护一个布尔变量。

官方文档：https://pkg.go.dev/flag#FlagSet.BoolFunc

最重要的边界是：BoolFunc 不是“自动累加的布尔值”。它是一种事件式入口，重复次数、调用顺序和回调返回的错误，都应该由你的程序明确处理。

先判断你要的是状态还是事件

传统的 Bool 适合表示最终状态：参数出现后，程序关心的是某个开关最后是否为真。比如 -dry-run、-debug 通常只需要一个结果。

但有些工具希望同一个无值开关每出现一次就增加一点行为强度，或者把同一类动作排入队列。此时“最后是 true”会丢失重复次数。BoolFunc 的价值在于保留每次出现这个事件的机会。

最小配方：重复一次就回调一次

下面的命令把 -verbose 定义成一个无显式值的布尔开关。回调不直接打印复杂业务结果，而是把每次出现转换成计数，解析完成后再统一决定输出级别。

package main

import (
	"flag"
	"fmt"
)

func main() {
	var verboseCount int
	fs := flag.NewFlagSet("demo", flag.ContinueOnError)

	// 每看到一次 -verbose，就增加一次强度；回调参数通常是 "true"。
	fs.BoolFunc("verbose", "重复出现以提高详细程度", func(value string) error {
		verboseCount++
		return nil
	})

	// Parse 只负责解析；错误会由调用方统一处理，不在回调里退出进程。
	if err := fs.Parse([]string{"-verbose", "-verbose"}); err != nil {
		fmt.Println("解析失败:", err)
		return
	}

	fmt.Println("详细级别:", verboseCount)
}

这个写法的关键不是计数器本身，而是把“参数出现”与“最终输出”分开。将来要把每次出现改成追加日志选项、打开一个诊断通道，或者记录调用来源，只需要替换回调内部的动作。

重复参数的顺序会被保留

命令行解析按参数列表从左到右处理。对于同一个 BoolFunc，回调会按出现顺序执行，因此可以把回调看成一条很小的事件流。不过，回调里最好只做确定性、轻量的状态更新，不要在参数解析期间启动 goroutine、写多个外部系统或依赖尚未解析的其他参数。

package main

import (
	"flag"
	"fmt"
)

func main() {
	var actions []string
	fs := flag.NewFlagSet("order", flag.ContinueOnError)

	// 每次回调都保存一个事件，方便 Parse 返回后按原顺序执行副作用。
	fs.BoolFunc("trace", "记录一次追踪请求", func(value string) error {
		actions = append(actions, "trace")
		return nil
	})

	if err := fs.Parse([]string{"-trace", "-trace", "-trace"}); err != nil {
		fmt.Println("解析失败:", err)
		return
	}

	// 解析结束后再执行真正的动作，生命周期和错误边界更清楚。
	for index, action := range actions {
		fmt.Printf("第 %d 次动作: %s\\n", index+1, action)
	}
}

如果回调本身就需要拒绝重复次数，也可以在回调中维护上限并返回错误。但要注意：错误代表参数值解析失败，应该让外层处理，而不是悄悄忽略。

显式值和错误返回要单独看

BoolFunc 的定义不要求用户为开关提供值，常见形式是 -trace 或 --trace。它不是接收任意布尔文本的通用字符串参数。如果业务必须允许用户写出 -trace=false 并据此撤销一次动作，就应该重新评估 API：最终状态用 Bool，每次带值的回调用 Func，不要把两种语义混在一个开关里。

package main

import (
	"errors"
	"flag"
	"fmt"
)

func main() {
	var count int
	fs := flag.NewFlagSet("limit", flag.ContinueOnError)

	fs.BoolFunc("once", "最多允许出现两次", func(value string) error {
		count++
		// 超出业务上限时返回解析错误，让调用方停止继续执行。
		if count > 2 {
			return errors.New("once 最多出现两次")
		}
		return nil
	})

	if err := fs.Parse([]string{"-once", "-once", "-once"}); err != nil {
		fmt.Println("参数无效:", err)
		return
	}
	fmt.Println("通过的次数:", count)
}

这里的 count 在第三次回调时已经递增，然后回调返回错误；如果你需要失败后仍保持对象处于可重试状态，就应在返回错误前恢复状态，或把待提交的变化先放到临时变量里。

Bool、Func 和自定义 Value 怎么选

几个 API 看起来都能处理命令行输入，但它们表达的意图不同。先写清楚“参数代表状态、事件还是带值命令”，通常就不会选错。

一个实用判断是：如果你最后只想知道“有没有出现过”，BoolFunc 可能过度设计；如果你需要知道“出现了几次、按什么顺序出现”，BoolFunc 才真正发挥作用。

把副作用放到 Parse 之后

在真实 CLI 中，BoolFunc 回调通常只收集意图，解析完成后才读取其他参数并执行动作。这样既能保证所有选项都已解析，也能让错误集中在一个流程里。

package main

import (
	"flag"
	"fmt"
)

func main() {
	var reloads int
	var configPath string
	fs := flag.NewFlagSet("service", flag.ContinueOnError)
	fs.StringVar(&configPath, "config", "service.yaml", "配置文件路径")

	fs.BoolFunc("reload", "请求一次重载", func(value string) error {
		// 回调只记录用户意图，不在配置还未解析时打开文件。
		reloads++
		return nil
	})

	if err := fs.Parse([]string{"-reload", "-config", "prod.yaml", "-reload"}); err != nil {
		fmt.Println("参数无效:", err)
		return
	}

	// 所有参数已就绪，再按收集到的次数执行服务动作。
	fmt.Printf("配置=%s，需要重载=%d 次\\n", configPath, reloads)
}

如果回调需要读取外部资源，建议把资源准备和参数解析拆成两步。这样用户写错参数时不会留下半完成的外部状态，重复调用也更容易测试。

常见问题

BoolFunc 重复出现时只会保留最后一次吗？

不会。它的设计就是每次看到该标志都调用一次回调；是否计数、排队或合并，由回调自己决定。

可以用 BoolFunc 接收 -debug=false 吗？

不要把它当成带值布尔参数使用。需要显式 true 或 false 时优先使用 Bool；需要每次接收一个字符串值时使用 Func。

回调返回错误后还应该继续执行吗？

通常不应该。返回的非 nil 错误会被当作 flag 值解析错误，外层应停止业务执行并向用户输出参数问题。

什么时候自定义 Value 更合适？

当参数格式复杂，或者需要同时实现解析、累加、格式化和自定义错误时，使用 flag.Value 更清晰；不要为了计数一个无值开关而增加自定义类型。

一句话总结：Bool 保存状态，BoolFunc 接住无值重复事件，Func 处理带值事件；先确定命令行语义，再决定回调里只收集意图还是直接执行动作。