OnceValue 初始化错误缓存后的恢复策略

使用 sync.OnceValue 做延迟初始化时，一个容易被忽略的事实是：它缓存的不是“成功状态”，而是初始化函数返回的那个值。如果返回值里带着 error，第一次失败产生的错误也会跟着结果被复用，后续调用不会自动再试。需要恢复时，应当创建新的 getter，或者改成显式管理“未初始化、初始化中、成功、失败”的状态；不能把旧闭包里的 sync.Once 当成可重置开关。

官方地址：https://pkg.go.dev/sync

如果初始化失败是暂态故障，优先让恢复策略位于 OnceValue 之外：低频人工刷新可以替换一个新的 getter；需要自动重试时，则使用自己的状态机控制重试窗口和并发。

OnceValue 为什么会留下初始化错误

OnceValue 返回一个可以并发调用的函数，内部只执行一次传入的初始化函数，并把返回值交给每个调用方。它并不理解返回值里的业务含义，所以“配置为空”“连接失败”“远端暂时不可用”等错误对象，和正常配置一样都是可缓存的结果。

下面的例子用一个结果结构体承载配置和错误。这样写的重点不是让 OnceValue 识别错误，而是明确告诉读者：一旦第一次调用返回 Err，同一个 getter 后续仍会拿到这份结果。

type initResult struct {
    Config *Config
    Err    error
}

var loadConfig = sync.OnceValue(func() initResult {
    cfg, err := fetchConfig()
    // 把错误作为结果的一部分返回，便于调用方决定是否降级。
    return initResult{Config: cfg, Err: err}
})

这时调用方通常会写成 result := loadConfig()，再判断 result.Err。如果 fetchConfig 第一次因为网络抖动失败，loadConfig 并不会在第二次调用时重新执行 fetchConfig。

先区分返回错误和 panic

返回错误和主动 panic 是两种不同的恢复边界。前者可以把错误放进业务结果，让上层决定是否降级；后者则会被 OnceValue 记住，后续调用继续触发同一个 panic。对于不应让进程直接中断的外部依赖初始化，通常更适合返回一个带错误字段的结果结构体。

var loadSchema = sync.OnceValue(func() *Schema {
    schema, err := fetchSchema()
    if err != nil {
        // panic 会被 OnceValue 记住；这里用 nil 表示不可用状态。
        log.Printf("load schema: %v", err)
        return nil
    }
    // 成功后返回的对象会被同一个 getter 持续复用。
    return schema
})

不过，返回 nil 会丢失具体错误。如果调用方需要区分“暂时失败”和“配置本身无效”，应使用前面的结果结构体，或使用 sync.OnceValues 返回值与错误。无论选择哪种形式，旧 getter 都不会因为错误被重新标记为未完成。

失败后显式重建 getter

如果初始化是低频动作，例如管理员刷新配置或服务启动后的手工恢复，可以把“创建一次性 getter”单独封装起来，并在失败后替换它。替换的是闭包变量，不是尝试修改闭包内部的 sync.Once。

type Loader struct {
    mu   sync.RWMutex
    load func() initResult
}

func newGetter() func() initResult {
    // 每次创建都会得到新的 OnceValue 和新的缓存边界。
    return sync.OnceValue(func() initResult {
        cfg, err := fetchConfig()
        return initResult{Config: cfg, Err: err}
    })
}

func NewLoader() *Loader {
    return &Loader{load: newGetter()}
}

func (l *Loader) Get() initResult {
    l.mu.RLock()
    getter := l.load
    l.mu.RUnlock()
    // 锁外调用 getter，避免把慢初始化占在读锁里。
    return getter()
}

func (l *Loader) Refresh() {
    l.mu.Lock()
    l.load = newGetter()
    l.mu.Unlock()
}

Refresh 只负责安装一个新 getter，真正的初始化仍然发生在下一次 Get。这样可以避免刷新线程直接执行慢操作；但如果多个请求同时发现错误并同时刷新，仍可能不断替换闭包，因此刷新入口最好由单一管理者、限流器或带冷却时间的机制控制。

需要自动重试时改用状态机

如果业务要求“失败后下一次调用可以重试”，可以不用 OnceValue 表达这个语义，而是自己保留未就绪状态。最小实现可以在互斥锁保护下完成一次初始化尝试；失败时不设置 ready，下一次调用自然会再次尝试。

type RetryableLoader struct {
    mu    sync.Mutex
    ready bool
    cfg   *Config
}

func (l *RetryableLoader) Get() (*Config, error) {
    l.mu.Lock()
    defer l.mu.Unlock()

    if l.ready {
        // 成功结果只读取一次，后续调用不再访问外部依赖。
        return l.cfg, nil
    }

    cfg, err := fetchConfig()
    if err != nil {
        // 失败不进入 ready，调用方下次仍可触发重试。
        return nil, err
    }
    l.cfg = cfg
    l.ready = true
    return l.cfg, nil
}

这个版本把慢调用放在互斥锁内，优点是不会让多个 goroutine 同时冲向依赖，缺点是一次失败或慢请求会让其它调用等待。生产代码可以进一步增加重试间隔、失败缓存时间、后台刷新或单航班机制，但这些都是业务策略，不能由 OnceValue 自动推断。

并发与恢复边界

落地时可以按下面几项检查：

还要注意：不要复制已经使用过的同步对象，不要在持有 Loader 的锁时调用可能回调 Get 的外部代码，也不要把“重建 getter”误写成对旧闭包的重新赋值。旧闭包仍可能被已经取到它的调用方使用，所以替换策略要配合对象生命周期和旧配置的释放时机。

总结

sync.OnceValue 适合“只初始化一次，成功或失败结果都固定”的语义。若把 error 放进返回值，错误就会和普通结果一样被缓存；若初始化函数 panic，后续调用也会重复 panic。需要恢复时，低频场景可以在外部显式创建新的 getter；需要自动重试时，应使用自定义状态机、重试窗口和并发控制。

相关问题

• OnceValue 能不能手动清空缓存？不能直接清空。应当丢弃旧 getter 并创建新的 OnceValue 闭包。
• OnceValue 和 OnceValues 怎么选？单个业务结果用 OnceValue；需要同时返回值和 error 时，OnceValues 或结果结构体更直观。
• 初始化失败后是否一定要重试？不一定。权限、参数和版本不兼容类错误应先修复原因，避免用重试放大故障。