Go sync 怎样让 OnceValue 的 panic 语义可预测

如果一个值需要延迟初始化，而且初始化过程只允许发生一次，sync.OnceValue 很适合把“执行一次”和“保存结果”合并起来。它的关键并不是简单地缓存返回值：初始化函数一旦 panic，返回的闭包也会记住这个 panic，之后每次调用都会再次抛出同一个值，而不会自动重试。

因此，调用方要先决定失败是否属于不可恢复的程序状态。能通过下一次调用恢复的网络、文件或配置错误，应让初始化函数返回 (T, error) 并使用 sync.OnceValues；只有确实要把失败固定成进程级契约时，才把 panic 放进 OnceValue。

OnceValue 的调用结构先看清

官方签名是 func OnceValue[T any](f func() T) func() T。外层调用接收初始化函数，返回一个没有参数的闭包。多个 goroutine 可以同时调用这个闭包，但真正执行 f 的只有一次，成功后的结果存放在闭包关联的状态中。

package main

import (
    "fmt"
    "sync"
)

func main() {
    calls := 0
    loadConfig := sync.OnceValue(func() string {
        calls++ // 只在初始化阶段执行，真实项目中可替换为配置读取。
        return "ready"
    })

    first := loadConfig()
    second := loadConfig()
    fmt.Println(first, second, calls) // 结果示意：ready ready 1
}

这里的 calls == 1 只说明初始化函数被调用一次，不代表每次调用都重新计算。若初始化函数捕获了可变变量，也不要把闭包外的变量当成共享状态同步工具；需要保护的外部状态仍应单独设计。

panic 为什么会变成稳定的调用契约

源码把“是否成功完成”与“保存的 panic 值”分开记录。初始化函数正常返回后，结果有效；如果初始化函数 panic，结果无效但 panic 值会被保留下来。首次调用会立即 panic，后续调用在一次性动作结束后发现结果无效，于是再次抛出同一个 panic 值。

package main

import (
    "fmt"
    "sync"
)

func main() {
    load := sync.OnceValue(func() string {
        panic("invalid immutable configuration") // 该失败会成为后续调用的固定契约。
    })

    for i := 0; i 

这意味着 recover 只能改变当前调用点的处理方式，不能让 OnceValue 重新尝试初始化。若业务需要“失败后下次再试”，就不能把重试责任放在这个闭包上。

错误模型要在 API 设计时选定

尤其要注意：OnceValue 没有“清空缓存”的方法。如果配置热更新、租约过期或连接重建属于需求本身，就需要把生命周期放到更高层，用可替换的函数或显式状态机管理，而不是期待 OnceValue 重新初始化。

上线前的边界检查

• 初始化函数是否只依赖启动期不变的输入？如果依赖请求参数，就不应放进无参数闭包。
• panic 是否代表当前进程无法继续，而不是一次普通的外部错误？
• 并发调用是否只读取不可变结果，还是还会修改闭包外的共享变量？
• 是否已经在设计文档中说明“只执行一次”和“失败后不重试”这两个约束？

常见问题

OnceValue 的 panic 会不会只发生第一次？

不会。初始化函数只执行一次，但返回闭包会在后续调用中继续 panic，并使用同一个 panic 值。

recover 之后能不能让 OnceValue 再试一次？

不能。recover 只接住当前调用的 panic，OnceValue 的一次性状态已经结束；要重试应设计可返回 error 的初始化流程。

OnceValue 和 OnceValues 怎么选？

不可恢复的失败可以用 OnceValue 表达稳定契约；需要把失败交给调用方判断时，用 OnceValues 返回值和 error 更清晰。

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