flag 自定义 FlagSet 如何避免污染全局参数

在一个 Go 进程里同时处理多个命令、子命令或测试时，直接调用 flag.String 和 flag.Parse 很容易把参数注册到同一张全局表。这样不仅会让不同入口看到彼此的参数，测试重复初始化时还可能遇到重复定义；解析失败则可能按默认策略直接结束进程。

解决办法是让每个入口自己创建 flag.FlagSet：用 NewFlagSet 指定名字和错误策略，把参数绑定在这张独立集合上，再显式传入不含命令名的参数切片。下面只围绕标准库 flag 的这一层边界展开。

先看问题：全局参数为什么会互相影响

包级函数操作的不是临时对象，而是 flag.CommandLine。只要一个包在初始化阶段注册了参数，其他入口随后调用包级 Parse 时就会共享这份状态。命令入口和测试入口因此被绑在同一张参数表上。

全局集合适合非常小的单入口程序；一旦参数解析被封装成可复用函数，就应把参数定义和解析对象一起收进函数或命令处理器里，不让调用方依赖隐式全局状态。

用 NewFlagSet 建立独立解析边界

flag.NewFlagSet(name, errorHandling) 会返回一张新的空参数集合。参数定义改用集合的方法，例如 fs.String；解析改用 fs.Parse(args)，其中 args 不应包含程序名。

package main

import (
	"flag"
	"fmt"
	"io"
)

// parseStart 只管理 start 命令自己的参数，不触碰全局 CommandLine。
func parseStart(args []string, output io.Writer) error {
	fs := flag.NewFlagSet("start", flag.ContinueOnError)
	// 把帮助和解析错误交给调用者，避免库函数直接退出进程。
	fs.SetOutput(output)
	addr := fs.String("addr", ":8080", "监听 `address`")
	verbose := fs.Bool("verbose", false, "输出详细日志")

	// Parse 的参数切片只包含命令后的内容，不包含程序名和 start。
	if err := fs.Parse(args); err != nil {
		return fmt.Errorf("解析 start 参数失败: %w", err)
	}
	if fs.NArg() != 0 {
		return fmt.Errorf("存在未处理的位置参数: %v", fs.Args())
	}
	fmt.Fprintf(output, "addr=%s verbose=%t\\n", *addr, *verbose)
	return nil
}

这里的关键不是把 flag 换成另一个包，而是把状态从包级变量变成函数内的 FlagSet。同一进程可以再次调用 parseStart，每次都会得到新的参数表；测试也可以传入自己的参数切片和输出缓冲区。

错误策略怎么选：优先看调用边界

NewFlagSet 的第二个参数决定 Parse 失败后的行为：

示例选择 ContinueOnError，因为解析函数没有权力决定整个进程是否退出。调用者可以记录错误、返回退出码，或在测试中断言错误内容。若要让帮助和错误输出进入缓冲区，也应在解析前调用 SetOutput。

常见误区：独立集合仍要保持参数生命周期清晰

第一，不要只把 Parse 换成 fs.Parse，却仍然用包级 flag.String 注册参数；这样注册阶段仍然污染全局集合。第二，传给 fs.Parse 的切片应从当前命令的参数开始，程序名和子命令名要在上层先剥离。第三，解析成功不等于业务输入完整，位置参数还要用 NArg、Args 明确处理。

如果函数会被多次调用，不要把 *string 或 *bool 指针保存到下一次调用；读取并转换成当前请求所需的配置对象后再返回，更容易保持边界清楚。

结语：把 FlagSet 当成一次解析的局部状态

避免全局参数污染的最小规则可以记成三句：参数定义使用同一个 FlagSet 的方法；解析使用 fs.Parse(args)；错误策略按调用边界选择。这样命令、测试和可复用函数各自拥有清晰的参数表，解析失败也不会在不知情的情况下终止整个进程。

相关问题

FlagSet.Parse 的参数里要不要放程序名？

不要。官方 API 约定传入不包含命令名的参数列表，例如只传 []string{"-addr", ":9000"}。

测试中为什么更常用 ContinueOnError？

因为测试需要拿到返回错误并检查输出，避免解析失败触发进程退出，导致测试无法继续断言。

能否把多个子命令都注册在同一个 FlagSet？

可以，但那会重新形成共享状态。若每个子命令有不同参数，通常为每个命令创建独立 FlagSet 更容易隔离定义、错误和位置参数。