应使用 functional options 模式而非结构体字面量传参，因其避免硬编码、支持可选配置、防止序列化污染、统一管理默认值、保障类型安全且组合灵活；option 应定义为函数类型别名 type option func(*config)，各 withxxx 函数返回闭包，校验逻辑应延后至构建后执行。
为什么不用结构体字面量直接传参
因为硬编码字段会快速失控：新增配置项要改所有调用点，可选字段得配零值或指针，还容易漏掉 omitempty 导致序列化污染。更麻烦的是，一旦结构体暴露给外部，字段语义和默认值就失去控制权。
Functional Options 的核心是把「配置行为」封装成函数，让调用方只关心「我要设什么」，不关心「这个值存在哪」。
- 每次新增选项不破坏旧代码，老调用点完全不受影响
- 默认值统一收口在构造函数里，不会散落在各处
- 类型安全——
func(*Config)不能误传成string或其他类型 - 组合自由：
NewClient(WithTimeout(5*time.Second), WithRetry(3))比&Client{Timeout: ..., Retry: ...}更易读、更难错
如何定义一个干净的 Option 类型
必须用函数类型别名，而不是接口或结构体。常见错误是定义成 type Option interface{ Apply(*Config) } —— 这样会失去类型推导，IDE 无法跳转，也拦不住用户传入非法实现。
正确写法就一行：
立即学习“go语言免费学习笔记（深入）”；
type Option func(*Config)
然后每个具体选项就是闭包：
func WithTimeout(d time.Duration) Option {
return func(c *Config) {
c.Timeout = d
}
}
- 不要在
WithXXX函数里做校验（比如if d panic），那是 <code>Apply阶段的事，或留给运行时检查 - 避免在闭包里捕获大对象（如整个
*http.Client），防止意外内存泄漏 - 如果需要链式调用（比如
WithLogger().WithLevel()），那就得另起一套 builder 模式，别硬塞进 Functional Options
Option 执行顺序会影响结果吗
会影响，而且影响很实在——后执行的 Option 会覆盖先执行的。比如 WithTimeout(10*time.Second), WithTimeout(2*time.Second)，最终生效的是 2 秒。
这不是 bug，是设计使然。但容易被忽略的是：某些选项之间有隐含依赖，比如 WithTLSConfig 和 WithInsecureSkipVerify，后者必须在前者之后执行才有效。
- 文档里必须写清依赖关系，或者干脆禁止冲突选项共存（在
Apply阶段检测并 panic） - 不要指望调用方按“合理顺序”传参，他们可能从配置文件动态加载选项列表
- 如果顺序敏感，建议把相关逻辑合并到一个 Option 里，比如
WithTLS(tls.Config, skipVerify bool)，而不是拆成两个
什么时候该放弃 Functional Options
当配置项极少（≤3 个，且全是必填）、生命周期极短（比如只在测试中构造一次）、或需要深度嵌套/条件分支时，它反而增加认知负担。
典型反模式：
- 只有
WithDB(*sql.DB)一个选项，其余全靠结构体字段传 —— 不如直接暴露func NewX(db *sql.DB, cfg Config) - Options 里开始出现
if env == "prod"或switch mode分支 —— 这说明配置逻辑已经越界，该抽成独立初始化流程了 - 为了支持泛型而强行把 Option 定义成
func[T any](T) Option—— 泛型 Option 会破坏类型收敛，让 IDE 和 go vet 失效
Functional Options 是为「稳定接口 + 渐进扩展」服务的，不是银弹。真遇到复杂配置场景，优先考虑 Builder + Validation 组合，而不是往 Option 壳子里硬塞逻辑。
