Go sync.OnceFunc 怎样缓存一次初始化函数

如果一个初始化动作可能被多个请求、多个 goroutine 或多个业务入口触发，真正需要缓存的往往不是某个返回值，而是“初始化已经完成”这件事。sync.OnceFunc 正好把这个动作封装成一个可重复调用的闭包：底层函数最多执行一次，后续调用只复用已经完成的状态。

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

最小用法是先把初始化函数传给 sync.OnceFunc，再让所有调用方共享返回的闭包。初始化函数正常返回后，所有并发调用都会在同一个初始化结果之后继续；如果初始化函数 panic，后续调用会复现相同的 panic，而不是自动重试。

先看清 OnceFunc 缓存的是什么

OnceFunc 的签名是 func OnceFunc(f func()) func()。它接收一个无返回值函数，返回另一个无返回值函数。因此它缓存的是一次性动作的完成状态，不是配置对象、连接句柄或计算结果本身。

把这个关系放到数据生命周期里，可以分成四个稳定节点：初始化入口保存 f，闭包保存 sync.Once 状态，第一次调用完成共享状态写入，后续调用只等待并继续。这个闭包应当被保存到长期可访问的位置，不能每次请求重新创建。

用一个闭包承接一次性初始化

下面的例子模拟加载进程级配置。initConfig 可以被多个入口调用，但真正的初始化逻辑只写一份，也不会因为调用方不同而重复执行。

package main

import (
    "fmt"
    "sync"
)

var loadConfig = sync.OnceFunc(func() {
    // 这里只放一次性初始化，例如解析配置或建立只读索引。
    fmt.Println("load config")
})

func handleRequest() {
    // 所有请求入口都共享同一个闭包，不要在这里重新调用 OnceFunc。
    loadConfig()
    fmt.Println("use config")
}

func main() {
    // 多次调用只会打印一次 load config，之后继续使用已完成的状态。
    handleRequest()
    handleRequest()
}

关键点有两个。第一，sync.OnceFunc 要在共享生命周期内创建，例如包级变量、服务对象字段或由构造函数返回的依赖；第二，调用方只负责调用闭包，不要再用一个布尔值包住它做“双重检查”。Go 内存模型明确说明，Once 的初始化完成会同步到其他调用的返回点，手写标记反而容易引入竞态。

并发调用时怎样理解等待关系

返回的闭包可以被多个 goroutine 同时调用。第一次进入的调用负责执行初始化函数，其他调用不会并行执行同一个函数，而是等待它结束。初始化函数完成后，这些调用才继续访问由初始化动作准备好的共享状态。

var prepare = sync.OnceFunc(func() {
    // 这里可以填充只读表、注册一次性资源或准备本地缓存。
    buildLookupTable()
})

func lookup(key string) string {
    // 先完成初始化，再读取共享数据；不要绕过 prepare 直接读表。
    prepare()
    return lookupTable[key]
}

这个模式适合“初始化动作没有返回值，但会准备其他共享对象”的场景。它不代表后续数据永远正确，也不负责刷新、重载或失效策略；如果配置需要定期更新，应把刷新生命周期设计在另一个明确的组件里。

panic、重复调用和返回值边界

OnceFunc 的一次性语义也覆盖失败状态。若传入函数 panic，第一次调用会把 panic 继续抛出，后续调用仍会抛出同一个值，不会因为再次调用而自动重试。初始化失败后若需要重试，应由业务层显式重建一个新的闭包，并同步处理旧状态，而不是期待原闭包恢复。

还要区分三个相近需求：

最后检查一下边界：闭包必须被复用，初始化函数要尽量短小且具备清晰的失败处理；不要把需要每次请求执行的逻辑放进去，也不要把需要返回错误的加载流程硬塞进无返回值函数。若初始化失败需要把错误交给调用方，通常应把错误保存到共享状态，或直接选择能表达该结果的其他设计。

常见问题

OnceFunc 会在 panic 后再次尝试初始化吗？

不会。它会保留 panic 值，后续调用继续 panic；想重试必须由业务层创建新的闭包并替换旧状态。

每次调用 sync.OnceFunc 都能实现一次初始化吗？

不能。每次创建都会得到一套新的 Once 状态，应该在共享生命周期内创建一次，再把返回闭包交给所有调用方。

总结起来，sync.OnceFunc 解决的是“一个无返回值初始化动作由多个并发入口共享”的生命周期问题：创建一次、调用多次、底层执行一次；正常返回后继续复用，panic 后保持同一失败语义。