Go Client 配置怎么设计：Functional Options 什么时候适合用，什么时候不值得

一个 HTTP Client 最初只有地址和超时，构造函数写成 NewClient(endpoint, timeout) 很顺手。后来要加重试次数、请求头、日志、代理和连接复用策略，参数列表很快变成一串同类型值。调用点还能编译，但读代码的人已经分不清第三个 5 是重试次数、最大空闲连接，还是别的开关。

先把构造函数压回“必填的两个值”

我更愿意先把真正不能省的东西留在参数位：例如服务地址和认证信息。其余带合理默认值的行为，再交给选项。调用点能读出每一次偏离默认值的理由：

client, err := NewClient(
	"https://inventory.internal",
	WithTimeout(800*time.Millisecond),
	WithRetry(2),
)
if err != nil {
	return err
}

这段代码的价值不在于少写几个逗号，而在于参数名称留在调用点。改成 NewClient(url, 800*time.Millisecond, 2, true) 以后，第四个布尔值的含义需要跳到定义处才能确认；选项写法把“设置了什么”留在眼前。

Go 官方关于模块兼容性的说明提醒过：给已有函数增加参数，哪怕采用可变参数，也不能保证所有旧用法兼容；函数值赋值等位置仍会因为类型变化失败。选项或配置对象的意义，正是在设计早期为未来的可选行为留出一个不必改签名的入口。

最小实现要把默认值和校验放在一起

下面的版本没有引入额外框架。Option 只负责修改内部配置；NewClient 先放默认值，再按顺序应用选项。这样每个选项的边界都靠近它自身，而不是散落在调用方。

type clientConfig struct {
	timeout    time.Duration
	retry      int
	timeoutSet bool
}

type Option func(*clientConfig) error

func WithTimeout(d time.Duration) Option {
	return func(c *clientConfig) error {
		if d  3 {
			return errors.New("retry must be between 0 and 3")
		}
		c.retry = n
		return nil
	}
}

func NewClient(endpoint string, opts ...Option) (*Client, error) {
	cfg := clientConfig{timeout: time.Second, retry: 1}
	for _, opt := range opts {
		if opt == nil {
			return nil, errors.New("nil option")
		}
		if err := opt(&cfg); err != nil {
			return nil, err
		}
	}
	return &Client{endpoint: endpoint, timeout: cfg.timeout, retry: cfg.retry}, nil
}

这里有两个刻意的决定：默认超时和重试次数只在一个地方出现；WithTimeout 不允许出现两次。不是所有项目都要拒绝重复项，但必须选定一种语义：报错、后者覆盖前者，或把重复值合并。Go 官方文章也把“同一选项给两次怎么办”列为函数选项的一个缺点；不写规则，调用顺序就会变成隐藏协议。

它解决的是 API 变化压力，不是所有配置问题

把 Functional Options 当作架构模式时，先看它承受的压力。它比较适合库作者需要维持稳定入口，而调用者只偶尔改一两个行为的 Client、连接器或服务组件。新加 WithHeader 不会迫使旧调用点补参数，默认行为也能继续保留。

反过来，如果配置项几乎总是一起出现，或你希望把配置写到文件、打印到日志、作为测试夹具复用，一组函数会掩盖配置的整体形状。此时直接暴露一个 Config 更诚实：

type Config struct {
	Timeout time.Duration
	Retry   int
	Headers map[string]string
}

func NewClientWithConfig(endpoint string, cfg Config) (*Client, error) {
	if cfg.Timeout == 0 {
		cfg.Timeout = time.Second
	}
	return &Client{endpoint: endpoint, timeout: cfg.Timeout, retry: cfg.Retry}, nil
}

两种方式不是互斥的。公开包可以给普通调用者一个简洁的 NewClient，同时给复杂场景一个 Config。但别把同一组字段同时散落在两套入口里却没有优先级说明；那会比长参数列表更难维护。

三种入口放在一起，判断会更快

有一个细节很容易被忽略：Config{Timeout: 0} 到底是“使用默认超时”还是“明确关闭超时”？如果业务需要区分这两种状态，结构体字段可能要用指针、额外布尔位，或改用选项表示显式意图。这个判断比选择模式名称更重要。

三个反例：这里别急着上 WithXxx

1. 只有一个可选开关。例如 NewParser(source, strict) 已经足够清楚；多建一个选项类型只会让最短路径变长。
2. 参数之间强相关。代理地址、用户名、密码和 TLS 设置本质是一组配置，拆成四个选项后，组合校验和脱敏输出反而更麻烦。
3. 你需要配置快照。如果启动前要把完整配置打印、比较或从 YAML 还原，结构体是更自然的载体；函数闭包并不方便序列化或检查。

模式的代价还包括包命名空间变大：每个 WithXxx 都是公开名字。名字越多，越要避免同义选项，例如既有 WithRetry 又有 WithRetries。我更建议先列出真正稳定的行为，再决定哪些值得成为公开选项。

落地前用这份清单收口

• 构造函数保留的参数是否真的是每次都必填？
• 默认值是否只定义一次，并且能从测试中观察到？
• 重复选项、nil 选项和非法值是否有明确结果？
• Config 与 Options 同时存在时，优先级是否写进包注释和测试？
• 新增一个选项后，旧调用点是否仍保持原来的行为？

Functional Options 很适合把“未来可能增加的少量可选行为”留在 API 外沿，却不适合替代所有配置对象。先看调用点是否真的因参数增长而变得难读，再选最小的入口，通常比先选一个流行模式更稳。

相关问题

Option 应该返回 error 吗？

只要选项可能带来无效范围、互斥组合或重复设置，返回 error 会让构造阶段尽早失败。全是简单字段赋值的内部小包，可以使用不返回 error 的版本，但仍要有测试覆盖默认值。

重复 WithTimeout 是后一个覆盖前一个，还是直接报错？

两种都可以，关键是稳定且可预测。基础设施 Client 更适合报错，避免调用顺序悄悄改变超时；可叠加的列表型配置才适合定义合并规则。

能把 Config 和 Options 混在同一个 NewClient 里吗？

能，但需要写清优先级，并尽量只保留一个默认值来源。若调用者要同时填写结构体和选项，说明入口可能已经需要拆分。

Functional Options 会影响性能吗？

它主要发生在构造阶段，普通 Client 初始化通常不是热路径。若对象创建量极大，再用基准测试比较闭包分配和实际业务开销，而不是先凭印象重写 API。