必须用 sync.Once 而非 if-nil 初始化延迟加载的 S3 客户端，否则并发下会多次初始化、重复建连或 nil panic；需配合 error 字段处理失败、按 namespace 隔离实例并显式校验错误。
延迟加载对象存储客户端必须用 sync.Once 而不是 if-nil 初始化
直接在方法里判空后 new 实例，是并发 panic 的高发区。多个 goroutine 同时进入 if p.client == nil 分支，会触发多次初始化、重复建连接、甚至 nil pointer dereference。正确做法是把初始化逻辑包进闭包，交给 sync.Once.Do 保证仅执行一次。
常见错误写法：if p.client == nil { p.client = newS3Client() }
正确封装结构：
type S3Proxy struct {
client *s3.Client
once sync.Once
}
func (p *S3Proxy) GetClient() *s3.Client {
p.once.Do(func() {
p.client = newS3Client() // 这里做实际构造，含 credential、region、timeout 等
})
return p.client
}
-
sync.Once是包级或结构体字段级变量，不能定义在函数内 - 闭包里捕获的变量（如 config）需确保生命周期覆盖整个初始化过程
- 若初始化可能失败（比如 credential 错误），需额外加 error 字段并返回，
sync.Once不会重试
代理结构体不能嵌入真实客户端，否则破坏访问控制
Go 没有语言级代理，靠接口+组合实现。如果写成 type S3Proxy struct { *s3.Client }，外部可直接调用所有 s3.Client 方法，绕过你本想加的日志、限流、熔断等逻辑。
必须显式定义接口，并只暴露受控方法：
立即学习“go语言免费学习笔记（深入）”；
type ObjectStorer interface {
PutObject(ctx context.Context, bucket, key string, data io.Reader) error
GetObject(ctx context.Context, bucket, key string) ([]byte, error)
}
type S3Proxy struct {
client *s3.Client // 私有字段，不导出
once sync.Once
}
- 真实
s3.Client必须为指针类型字段，且不导出（小写开头） - 所有对外方法都走
GetClient()获取实例，再转发调用 - 新增方法时只需改接口和 proxy 实现，不用动真实 client 结构
初始化失败后 sync.Once 不会重试，必须显式处理 error
sync.Once 的语义是“最多执行一次”，不管成功失败。一旦初始化函数 panic 或返回 error，后续调用 GetClient() 仍会返回 nil 或未初始化状态，但不再尝试重建。
典型修复模式是加一个 error 字段并透传：
type S3Proxy struct {
client *s3.Client
err error
once sync.Once
}
func (p *S3Proxy) GetClient() (*s3.Client, error) {
p.once.Do(func() {
client, err := newS3Client()
p.client = client
p.err = err
})
return p.client, p.err
}
- 调用方必须检查 error，不能假设
GetClient()总是返回有效 client - 不要在初始化函数里 recover —— 隐藏错误会让问题更难定位
- 若需重试，得自己实现带退避的初始化逻辑，
sync.Once不负责这个
多命名空间配置下延迟加载要按 namespace 隔离实例
像 Agollo 支持 NamespaceName: "s3-us-east-1,s3-eu-west-2" 这种多命名空间场景，每个 namespace 对应不同 region、credential、endpoint。不能共用一个 sync.Once 和 client 实例。
正确做法是用 map 缓存各 namespace 的 proxy 实例，并懒加载：
type S3MultiProxy struct {
clients sync.Map // key: namespace, value: *S3Proxy
}
func (p *S3MultiProxy) GetClient(ns string) (*s3.Client, error) {
if v, ok := p.clients.Load(ns); ok {
return v.(*S3Proxy).GetClient()
}
proxy := &S3Proxy{}
p.clients.Store(ns, proxy)
return proxy.GetClient()
}
-
sync.Map适合读多写少，避免全局锁；首次写入后基本只读 - namespace 名称必须规范（如全小写、不含特殊字符），否则 map key 查找失效
- 注意内存泄漏风险：长期不用的 namespace 实例不会自动清理，需配合 TTL 或显式卸载
