Go 应避免传统 Builder 模式，推荐函数选项（Functional Options）
在 Go 语言里，没有构造函数重载，也没有类继承。如果生搬硬套传统面向对象那套 Builder 模式，写出来的代码往往会显得别扭，甚至是一种反模式。问题的关键在于，你得用好 Go 自己的三样法宝：结构体字段初始化、函数选项（functional options）和方法链式调用。与其强行模拟 Ja va 风格，不如拥抱 Go 的惯用法。
为什么不能直接用 NewXXXBuilder() + SetXxx() + Build()？
原因其实很直接。Go 的结构体字段默认是可导出的（也就是 public 的），用户完全可以直接给字段赋值。这样一来，SetXxx() 方法就显得有些尴尬了——它既无法强制进行参数校验，又破坏了开发者对对象不可变性的预期。更麻烦的是，如果 Builder 结构体本身带有内部状态（比如，多个 SetXxx() 调用之间存在依赖关系或顺序要求），那么它很难保证并发安全，代码的复用性也会大打折扣。
那么，实践中应该怎么做呢？
- 把 Builder 设计成**无状态的纯配置载体**，或者更彻底一点，干脆不用独立的 Builder 类型，转而采用函数选项模式。
- 尽量避免在 Builder 内部维护“哪些 Set 方法已经被调用过”这类隐式状态标志位——Go 语言的设计哲学并不鼓励这种隐晦的状态管理方式。
- 如果确实需要链式调用，务必确保每个方法要么返回一个新实例（遵循值语义的复制），要么在文档中明确标注该方法会“修改原实例”（使用指针接收者）。
推荐做法：用函数选项（Functional Options）替代传统 Builder
这是 Go 社区广泛接受并推崇的惯用法。它清晰、灵活、没有副作用，并且天然支持配置的组合与复用。其核心是定义一个函数类型（比如叫 Option），然后把每一个配置项都封装成一个该类型的函数。
立即学习“go语言免费学习笔记（深入）”；
来看一个典型的例子：
type Config struct {
Timeout int
Retries int
Debug bool
}
type Option func(*Config)
func WithTimeout(t int) Option {
return func(c *Config) { c.Timeout = t }
}
func WithRetries(r int) Option {
return func(c *Config) { c.Retries = r }
}
func NewConfig(opts ...Option) *Config {
c := &Config{Timeout: 30, Retries: 3}
for _, opt := range opts {
opt(c)
}
return c
}
使用起来非常直观：NewConfig(WithTimeout(10), WithDebug(true))。代码可读性强，也易于测试。
不过，有几点需要注意：
- 所有的
Option函数必须接收*Config指针，否则无法修改原始的结构体。 - 如果配置项之间存在顺序敏感性（比如需要先调用
WithBaseURL再调用WithPath），必须在文档中明确说明，函数本身不会保证这种顺序逻辑。 Option函数只应该负责配置，不要在内部执行耗时操作或产生副作用（比如发起网络请求）。
什么时候才需要真正的 Builder 结构体？
只有当对象的构造过程涉及多阶段校验、需要缓存中间状态，或者必须延迟执行某些逻辑（例如解析模板、加载证书文件）时，才需要考虑使用显式的 Builder 类型。典型的应用场景包括 HTTP 客户端构建、数据库连接池配置以及 gRPC Dial 选项的组装。
如果决定使用 Builder，有几个实操要点需要把握：
- Builder 的字段应该设计为**不可导出**，同时提供导出的构造函数，防止用户绕过校验逻辑直接给字段赋值。
- 每一个设置方法都应返回
*Builder（使用指针接收者），并在方法内部进行最小必要校验（例如，if timeout < 0 { return errors.New("timeout must be > 0") }）。 Build()方法应该执行最终的一致性检查（比如，“TLS 已开启但未提供证书”就应该报错），并返回一个**不可变的对象**（可以将所有字段设为只读，或者返回一个接口类型来隐藏具体实现）。- 要避免在
Build()方法中执行 I/O 或阻塞操作；这些应该是使用者的责任，而非 Builder 的职责范围。
容易被忽略的坑：零值陷阱与并发安全
Go 结构体的字段默认为零值，而很多配置项的零值本身就是合法值（比如，int 类型的 0 可能表示“不限制重试次数”）。这时，你无法仅仅通过字段是否为零值来判断用户是否显式设置了它。
解决这个困境通常只有两个方案：
- 使用指针字段（例如
*int），用显式的nil来表示“未设置”。但这会增加解引用的开销和判空的代码量。 - 使用额外的布尔字段来标记（例如
timeoutSet bool）。这种方法简单直接，但会引入一些样板代码。
另一个常被忽略的问题是：Builder 实例本身，即使使用了指针接收者，如果被多个 goroutine 同时调用设置方法，它也**不是线程安全的**。除非你显式地加锁，否则应该假设 Builder 是一次性、单协程使用的工具。
当真正需要并发构建对象时，正确的做法是让每次调用都生成一个新的 Builder 实例，而不是尝试去复用同一个实例。
