链式调用必须返回指针，因为值接收者会复制结构体，导致状态无法累积；指针接收者配合返回 *T 才能确保所有调用作用于同一实例。
为什么链式调用必须返回指针而不是值
Go 中方法接收者如果是值类型，每次调用都会复制整个结构体；一旦结构体包含切片、map 或其他引用类型，复制后修改内部字段不会影响原始实例。链式调用要求每一步都操作同一个对象，所以 func (s *Stack) Push(v int) *Stack 必须返回 *Stack，否则后续调用作用在副本上，前序状态丢失。
- 值接收者方法：无法累积状态变更，
s.Push(1).Push(2)中第二个Push作用于第一个Push返回的副本，原始s和中间副本都未被正确串联 - 指针接收者 + 指针返回：确保所有调用指向同一内存地址，是链式调用的必要条件
- 注意：返回
self（即return s）即可，不要写return *s—— 后者会返回值类型，破坏链式
如何避免链式调用中意外的 nil panic
如果链式调用某一步返回 nil（比如构造失败、校验不通过），后续方法会在 nil 指针上调用，直接 panic。常见于初始化链或条件构建场景。
- 构造函数（如
NewClient()）应保证返回非 nil 指针，或明确文档说明失败时返回nil并要求调用方检查 - 避免在链中插入可能返回
nil的方法，例如：NewBuilder().WithHost(h).WithPort(p).Build()中Build()若可能失败，应拆成两步：b := NewBuilder().WithHost(h).WithPort(p); client, err := b.Build() - 若必须支持“可失败链”，可用泛型封装结果：返回
Result[*Client]类型，但此时已不属于纯粹链式调用语义
链式调用与不可变性冲突时怎么取舍
Go 没有内置不可变对象支持，但有些设计倾向返回新实例（如 strings.ReplaceAll）。若强行用指针实现链式，就等于默认接受可变性 —— 这在并发或复用场景下容易出错。
- 对外暴露链式 API 前，确认该类型是否本就应被共享和复用；否则优先考虑函数式风格：
config := ApplyTimeout(ApplyRetry(DefaultConfig(), 3), 5*time.Second) - 若坚持链式，应在文档中强调“调用链会修改原对象”，并在示例中提醒不要多 goroutine 共享同一实例
- 常见反模式：
c1 := NewClient().WithTimeout(10*time.Second); c2 := c1.WithTimeout(20*time.Second)—— 此时c1和c2实际指向同一对象，超时已被覆盖为 20 秒
嵌套结构体链式调用要注意字段可见性
当链式方法需要设置嵌套字段（如 req.Header.Set("X-Trace-ID", id)），而 Header 是未导出字段时，无法直接链式访问。必须提供透传方法。
立即学习“go语言免费学习笔记（深入）”；
- 错误写法：
req.Header().Set(...)如果Header()返回的是http.Header值类型副本，则后续Set不生效 - 正确做法：提供
WithHeader(key, value string) *Request方法，在内部调用r.header.Set(key, value)并返回r - 更安全的设计：把嵌套结构也做成链式类型，例如
req.Header().Set(...).Add(...)，但要求Header()返回*HeaderBuilder而非原始http.Header
type Config struct {
timeout time.Duration
retries int
}
func (c Config) WithTimeout(d time.Duration) Config {
c.timeout = d
return c
}
func (c Config) WithRetries(n int) Config {
c.retries = n
return c
}
// 使用
cfg := (&Config{}).WithTimeout(5 * time.Second).WithRetries(3)
链式调用本身不复杂，难的是判断什么时候不该用 —— 尤其当结构体字段需要并发安全、或调用链可能被缓存/复用时，返回指针带来的隐式共享很容易被忽略。
