Go sync.OnceFunc 怎样保证无参初始化只执行一次

将无参、无返回值的初始化函数交给 sync.OnceFunc，保存它返回的函数，并让所有调用者使用同一个包装函数，就能让原始初始化函数最多执行一次。创建包装函数不会立即初始化；首次调用返回的函数时才触发初始化。该接口从 Go 1.21 起提供。

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

目标与边界：一次对应哪个生命周期

先决定“一次”的范围。如果每个服务对象都需要独立初始化，就在对象构造时建立一个包装函数；如果整个进程只需要一份，就在进程共享位置建立。OnceFunc 不会根据原函数名称或函数指针做全局去重，两次独立包装会得到两个独立的一次性入口。

package main

import (
    "fmt"
    "sync"
)

func main() {
    // 包装只创建一次；每次调用都复用这个 ready 函数。
    ready := sync.OnceFunc(func() {
        fmt.Println("构建固定规则")
    })
    ready()
    ready()
}

按语义，固定规则的构建消息只应打印一次。本文示例未在本机运行，描述的是 API 保证与代码预期。若没有调用 ready，内部函数不会执行；因此“只执行一次”在严格含义上是最多一次。

全流程总览：创建、调用与使用结果

实际使用可以分为三个阶段：构造对象时保存包装入口，业务方法调用入口确保初始化完成，然后读取初始化产物。多个 goroutine 可以并发调用同一个入口；初始化尚未完成时，其他调用不会越过该入口去读取半成品。

这里的节点包括服务对象 Catalog、包装函数 ensure、原始函数 initRules，以及初始化产物 rules。业务方法 Lookup 依赖 ensure，也读取 rules。ensure 是共享入口，不应在每次 Lookup 内重新创建。

阶段拆解：按对象构造一次性入口

下面把初始化范围限定为一个 Catalog 对象。rules 在初始化完成后保持只读，因此后续查询不需要用 OnceFunc 保护每一次读取。若要增加动态修改，那是另一项同步设计。

package catalog

import "sync"

type Catalog struct {
    ensure func()
    rules  map[string]string
}

func NewCatalog() *Catalog {
    c := &Catalog{}
    // 构造阶段建立并保存入口；对象交给其他 goroutine 前完成这一步。
    c.ensure = sync.OnceFunc(c.initRules)
    return c
}

func (c *Catalog) initRules() {
    // 初始化产物随后只读，不在外部暴露可修改的 map。
    c.rules = map[string]string{
        "quick": "轻量任务",
        "batch": "批处理任务",
    }
}

func (c *Catalog) Lookup(key string) (string, bool) {
    // 每条读取路径都经过同一个 ensure，避免绕开初始化保证。
    c.ensure()
    value, ok := c.rules[key]
    return value, ok
}

这个类型要求通过 NewCatalog 创建，零值 Catalog 的 ensure 是 nil，不能直接调用 Lookup。生产代码若需要零值可用，应另行设计初始化入口，不能假设 nil 函数字段会自动获得一次性语义。示例没有打开文件或网络连接，所以没有资源关闭分支。

也不要复制已构造的 Catalog 并把它当作独立初始化对象：复制函数值仍引用同一个包装状态，闭包中的接收者仍是原对象。这里统一传递 *Catalog，使对象身份和初始化范围一致。

推荐流程：把失败策略放在选型之前

OnceFunc 接受 func()，没有 error 返回槽。如果内部函数 panic，之后对包装函数的每一次调用都会以相同的值再次 panic；它不会重试初始化。即使外层 recover 了某一次 panic，下一次调用仍不会把初始化重新执行一遍。

如果函数只是把失败写入变量后正常返回，一次性状态同样已经完成，后续也不会重试。需要同时取得结果与 error，可以考虑 OnceValues，但它仍缓存首次返回结果，不会因 error 非空自动重试。需要失败后重试、退避或刷新时，应使用明确的状态与同步机制，而不是重复调用 OnceFunc。

常见误区与速查表

推荐在自己的项目中分别覆盖未调用、重复调用、多个并发调用者与初始化失败几类情况，并检查所有读取路径都经过同一个入口。不要只在单线程里看到一次输出，就推断整个对象的生命周期和错误策略都已正确。这里没有虚构测试通过或运行性能。

相关问题

能取消正在等待初始化的调用吗？

返回函数没有 context 参数，也没有独立的取消接口。如果业务需要每个调用者都可取消等待，应另外设计等待与通知机制。

把返回函数赋值给另一个变量会重新初始化吗？

不会，复制函数值仍共享同一个包装状态。只有再次调用 OnceFunc 创建新包装时，才建立另一份状态。

可以重置已执行的包装函数吗？

没有 Reset 方法。运行中替换共享函数还可能引入数据竞争；若要换代，应在明确的对象生命周期和同步边界内构造新对象。

参考：Go sync.OnceFunc 官方文档。