Go sync.OnceValue 里返回错误后为什么不会自动重试

我第一次把配置文件加载封装成一次性函数时，最容易误判的地方就是把“只执行一次”理解成“失败后下次再试”。实际情况恰好相反：如果把错误作为普通返回值交给 sync.OnceValues，第一次调用得到什么，后面的调用就继续得到什么，底层函数不会自动重跑。sync.OnceValue 如果返回的是一个带错误字段的结果对象，也遵循同样的缓存语义。

官方文档：https://pkg.go.dev/sync#OnceValue

先看最小配方：error 也会被一起记住

下面的写法很短，也很容易被误用。sync.OnceValues 是 Go 1.21 加入的泛型辅助函数，它把 Config 和 error 都作为一次调用的结果保存下来。第一次读取失败后，第二次调用只会返回已保存的空配置和原来的 error。

package main

import (
    "errors"
    "fmt"
    "sync"
)

type Config struct {
    Endpoint string
}

func main() {
    attempts := 0
    load := sync.OnceValues(func() (Config, error) {
        // 用计数观察底层函数只会进入一次；真实项目这里可替换成文件或远程读取。
        attempts++
        return Config{}, errors.New("配置中心暂时不可用")
    })

    _, firstErr := load()
    _, secondErr := load()
    fmt.Println(attempts, firstErr == secondErr)
    // 输出示意：1 true。第二次没有重新请求配置中心。
}

这里的关键不是 error 是否为空，而是初始化函数有没有成功返回。只要函数正常返回，OnceValues 就会把这对结果视为最终结果。换句话说，error 是业务数据的一部分，不是让 sync.Once 自动重置的信号。

为什么“返回错误”不会触发第二次调用

标准库内部先用 sync.Once 保证初始化函数只进入一次，再把函数返回的两个值写入闭包状态。后续调用直接读取已经保存的结果。因此下表中的三种情况不能混为一谈：

这也是我在排查“第二次为什么没有刷新”的时候最先看的地方：如果代码里只有一个已经创建好的 load 闭包，那么调用它多少次，都不会让 Once 重新开放。重新执行的唯一前提，是重新建立一套新的闭包状态。

稳定结果用 OnceValues，临时失败改成显式重试

如果依赖是本地只读配置、内置字典或启动后不会变化的密钥表，缓存失败结果反而能避免请求风暴；调用方看到错误后直接让启动流程失败即可。如果依赖可能因为网络抖动恢复，就不要把它交给一次性缓存。可以只缓存成功值，失败时保留“未就绪”状态：

type RetriableConfig struct {
    mu       sync.Mutex
    load     func() (Config, error)
    value    Config
    ready    bool
}

func (r *RetriableConfig) Get() (Config, error) {
    r.mu.Lock()
    defer r.mu.Unlock() // 保证并发调用不会同时触发多次加载。

    if r.ready {
        return r.value, nil
    }
    value, err := r.load()
    if err != nil {
        // 失败不改变 ready；下一次调用仍可再次尝试。
        return Config{}, err
    }
    r.value = value
    r.ready = true
    return r.value, nil
}

// 初始化：loader := &RetriableConfig{load: readConfig}

这个最小实现每次失败都会重试，生产环境通常还要加超时、退避、最大尝试次数和指标。若不想让调用者在短时间内反复触发，也可以额外记录 nextRetryAt，把“是否允许本次尝试”放在同一把锁内判断。

三个常见坑，先分清语义再改代码

• 把 error 当成 panic。返回 error 不会中断 Once 的完成过程；只有 panic 才进入 panic 重放语义。
• 只在调用处加循环。循环调用同一个 load() 只会重复读取缓存；循环必须包住“重新创建加载状态”或改用显式加载器。
• 为了重试直接并发重建闭包。这样可能让多个 goroutine 各自发起初始化请求；若需要并发安全，重试状态和成功值要由 mutex 或其他同步机制统一保护。

相关问题

OnceValue 能直接返回 error 吗？

可以，但它的泛型返回值只能是一个类型。常见做法是定义包含值和 error 的结果结构；如果希望自然地返回两个结果，使用 sync.OnceValues(func() (T, error)) 更清楚。

第一次失败后，手动再次调用 load 会重新读取吗？

不会。只要 load 还是同一个闭包，调用只会返回已缓存的结果。要重试，需要显式管理状态或创建新的 OnceValue/OnceValues 闭包。

配置加载应该默认重试吗？

不应该一概而论。本地固定配置更适合失败即终止并保留错误；远程配置或服务发现要结合超时、退避、熔断和启动策略，明确成功缓存的时机。

记住一句判断标准：sync.OnceValue 解决的是“结果只初始化一次”，不是“失败时自动再试”。当失败本身也是需要缓存的最终结论时用它；当失败只是暂态现象时，把重试状态写出来。