Functional options 是 Go 中构造可配置对象最稳妥的通用解法，尤其适用于字段超3个、含默认值或需未来扩展的场景；构造函数须用 func NewClient(opts ...Option) *Client，默认值初始化必须在遍历 opts 前完成，Option 类型应统一为 func(*Client) 或 func(*Client) error（依是否可能合法失败而定），所有 WithXXX 函数必须通过指针修改实例、禁止返回新 struct，并规避 IO/panic 风险操作。
Functional options 是 Go 里构造可配置对象最稳妥的通用解法，不是“可选”，而是“该用就用”——尤其当结构体字段超过 3 个、存在默认值、或未来可能扩展时。
func NewClient(opts ...Option) *Client 怎么写才不翻车
构造函数必须接收变参 opts ...Option，不能只收单个 Option。否则无法链式传多个选项，比如 NewClient(WithTimeout(5), WithRetries(3)) 会编译失败。
默认值初始化必须在遍历 opts 之前完成，且不能依赖用户传入的 option 来补全关键字段：
- 先写
c := &Client{timeout: 30 * time.Second, retries: 3} - 再
for _, opt := range opts { opt(c) } - 别把默认值逻辑塞进某个
WithXXX里——那会导致没传这个 option 就 panic
如果某个 option 可能返回 error（比如校验证书路径），构造函数必须检查并提前返回：if err := opt(c); err != nil { return nil, err }。忽略 error 是线上静默故障的常见源头。
立即学习“go语言免费学习笔记（深入）”；
type Option func(*Client) error 和 type Option func(*Client) 区别在哪
带 error 返回的签名更严谨，但不是所有场景都需要。核心判断依据是：这个配置项是否可能“合法失败”。
以下情况建议用 func(*Client) error：
-
WithTLSConfig(certPath string)—— 文件路径不存在或不可读 -
WithLogger(l log.Logger)—— 传了nillogger -
WithBaseURL(u string)—— URL 解析失败
而 WithTimeout(t time.Duration) 或 WithDebug(b bool) 这类纯赋值操作，用 func(*Client) 更轻量。混用两种类型会导致构造函数签名分裂，不推荐。
WithXXX 函数里最容易被忽略的三类副作用
Functional options 的语义是“声明式配置”，不是“初始化动作”。一旦引入副作用，就会破坏调用时机的可控性：
- 在
WithTimeout里调http.DefaultClient.Do()—— 构造时发请求，超时逻辑还没生效就卡死 - 在
WithMiddleware中直接append(c.middlewares, m)而不是c.middlewares = append(c.middlewares, m)—— 如果c.middlewares是nil，会 panic - 在
WithHeaders里没判空就写c.headers["User-Agent"] = "xxx"——c.headers是nil map，运行时 panic
正确做法是：map 字段先判空再初始化，切片字段用 append 安全追加，所有 IO/网络/文件操作一律推迟到 .Start()、.Do() 等实际执行方法中。
为什么 WithXXX 不能返回新 struct，而必须接收 *Client
因为 functional options 的本质是“修改已有实例”，不是“生成新实例”。如果写成：
func WithTimeout(t time.Duration) *Client {
c := &Client{}
c.timeout = t
return c
}那就退化成普通工厂函数，彻底失去组合能力：WithTimeout(5).WithRetries(3) 在 Go 里语法不合法，也无法和其它 option 统一传给 NewClient。
真正起作用的是闭包捕获 + 指针修改的组合：
func WithTimeout(t time.Duration) Option {
return func(c *Client) {
c.timeout = t // 直接改原始实例
}
}这种写法让所有 option 天然兼容同一个接口，也保证了多次调用时字段覆盖行为可预测——后调用的 option 总是最终生效的那个。
最常被跳过的细节是：option 函数内部对 map、slice、嵌套 struct 的赋值必须做防御性拷贝或判空，否则看似简单的 WithHeaders 可能在并发场景下引发 panic 或数据污染。
