Go sync.Once 怎样延迟初始化单例资源

Go 中延迟初始化单例资源，可以把 sync.Once、资源对象和初始化错误放在同一个长期存活的作用域里，由统一的 Get 函数调用 once.Do。第一次真正访问时才构造资源，并发访问者共用这一轮初始化结果。不要在 Get 内重新声明 Once，也不要在 Do 外先用普通变量判断资源是否为空。

我更愿意把“单例”理解为一个明确的资源归属约定，而不是到处可以读写的全局指针。下面以按需加载地区名称表为例：平时不使用就不读文件，一旦使用便固定这份数据。场景和代码是原创教学示例，不是已完成的线上故障复盘，也没有声称进行过本机压测。

多个入口为何会重复创建资源

假设两个业务入口都想读取同一份名称表。如果各自发现 registry 为空就开始加载，多个 goroutine 可能同时通过判断；单纯的 nil 判断既不能串行化初始化，也不能建立结果的安全发布关系。我会首先问：这些入口是否真的属于同一个资源生命周期？只有答案明确，才选择一次性初始化。

如果表按租户区分，或不同请求需要不同配置，一个包级单例就不合适。Once 只围绕一个实例提供约束，不会按资源名字建立全进程唯一性，也不会跨进程协调。部署多个服务进程时，每个进程都可以有自己的初始化动作。

先确认 Once 是否真的共享

排查重复加载时，我会沿着 Get 的调用关系寻找 Once 的声明位置。声明在包级意味着本包入口共用它；声明在每次调用的局部变量里，则每次访问得到一个全新的约束对象。若把它放入资源持有者结构体，也应通过指针共享持有者，而不是按值复制已使用过的对象。

另一个反直觉点是，同一个 Once 即使收到不同闭包，也不会为每个闭包分别执行一次。若 Get 接受 filename，首次初始化选中的文件就决定了后续结果。对本例，我选择固定文件名，让调用者不能用不同参数争抢单例配置；更复杂的项目应在构造持有者时冻结配置。

官方定义明确要求 Once 首次使用后不能复制。阅读入口：https://pkg.go.dev/sync。这个约束不只是避免重复劳动，还关系到共享结果的一致性。

让结果与错误一起留在资源包里

准备名为 regions.json 的文件，内容采用 JSON 对象，键是地区代号，值是显示名称。将下列代码放入 region 包：Get 返回完整 Registry 或初始化错误，Lookup 只提供查询，不暴露底层 names map。

package region

import (
    "encoding/json"
    "errors"
    "fmt"
    "os"
    "sync"
)

type Registry struct {
    names map[string]string
}

// 不向外暴露可变 map；初始化成功后只读。
func (r *Registry) Lookup(code string) (string, bool) {
    name, ok := r.names[code]
    return name, ok
}

var (
    once sync.Once
    registry *Registry
    initErr error
)

func Get() (*Registry, error) {
    once.Do(func() {
        // 本例约定部署前准备此文件，之后不做热更新。
        data, err := os.ReadFile("regions.json")
        if err != nil {
            initErr = fmt.Errorf("加载地区资源: %w", err)
            return
        }
        var names map[string]string
        if err := json.Unmarshal(data, &names); err != nil {
            initErr = fmt.Errorf("解析地区资源: %w", err)
            return
        }
        if len(names) == 0 {
            initErr = errors.New("地区资源不能为空")
            return
        }
        // 完成读取和解析后才发布完整对象。
        registry = &Registry{names: names}
    })
    return registry, initErr
}

闭包把 ReadFile、Unmarshal 和非空检查作为一次初始化动作。任何失败都写入共享 initErr 并提前返回；只有全部完成，才赋值 registry。本例不会生成一个“部分填充也能返回”的资源对象，也不会只把错误留在第一次调用的局部变量里，让后续调用误以为成功。

结构中的三个共享成员是 once、registry 和 initErr。Get 使用 once，初始化闭包产生 Registry 和初始化错误，Registry 持有 names map。这些组成关系是理解单例的核心，图里的连线不代表执行顺序。

对我来说，这种封装最有价值的地方是结果和错误都能被明确看见。调用者必须先检查 err，再使用返回对象。示例中的相对文件名仍依赖程序启动目录，这是文件加载层自己的约定，与 Once 是否共享无关；正式项目可以在启动配置中确定绝对路径，再冻结到持有者中。

如果使用 Go 1.21 或以上，sync.OnceValues 还能将返回两个值的初始化函数包装为并发可调用的函数，用来缓存对象与错误更简洁。但它同样缓存第一次调用的结果，不是自动重试器。采用前应确认项目的 Go 版本，而不是只替换函数名。

初始化失败为何不会自动重试

假设第一次 Get 时文件尚未部署。ReadFile 返回错误，本例把它保存在 initErr；初始化闭包正常返回后，这个 Once 的动作已经结束。随后补齐文件再调用 Get，仍会得到之前保存的错误，而不会再读文件。这是本例的一次尝试契约，不是 Once 把错误“吞掉”了。

我会把这种策略用于应当随部署固定、缺失就意味着配置不完整的资源。如果依赖是可能短暂不可用的远程服务，产品要求连接失败后继续重试，就不应仅靠 Once 包住第一次连接。需要另外设计互斥保护的初始化状态、重试间隔、失败共享与关闭条件，避免多个请求各自重试放大压力。

也不要在并发使用期间赋值一个零值 Once 来“重置”。重置、资源替换和正在读取的请求没有共同协调，会破坏原有生命周期约定。若确实要更新，应该创建新的持有者并通过另一个受控机制替换，或者使用专门的可更新资源管理方案。

初始化闭包若发生 panic，普通 Once 会把这次动作视为已执行，后续 Do 不会重跑。不要在外层 recover 之后把没有完成构造的对象当成可用资源；普通配置错误应通过 error 明确返回。OnceValues 对 panic 的后续调用行为与普通 Do 不同，不能混为一谈。

初始化之后的并发与生命周期

Get 的返回位置在 Do 之后。Go 内存模型保证初始化函数完成与各次 Do 返回之间的同步关系，因此共享调用者通过这个入口取得初始化写入的结果。不应额外加一个 Do 之外的 registry 非空“快速返回”，绕过统一同步入口。官方内存模型：https://go.dev/ref/mem。

这项保证只解决初始化发布，不会自动锁住资源以后的每个方法。本例的 names map 只在构造时写入，Lookup 仅查询；如果新增更新或删除操作，就必须重新设计同步，不能因为它“是 Once 创建的”就允许并发修改。

资源也不会因为 Once 结束而自动关闭。若换成文件句柄、客户端或连接池，谁能调用 Close、什么时候阻止新访问、何时等旧请求退出，都需要独立约定。我更倾向于由应用生命周期统一管理共享资源，避免某一个请求结束时关闭其他请求仍在使用的对象。

读者可以怎样确认行为

复查时，不只看程序是否“没有报错”。我会针对初始化次数、返回对象和失败保持性分别设计检查。以下是读者可在自己的测试环境实施的条件，本文没有据此声称获得实测结果。

• 让多个 goroutine 同时调用同一个 Get，用受同步保护的计数器观察构造函数是否只进入一次。
• 在成功场景比较各调用者返回的对象是否为同一对象，并确认 Lookup 返回约定数据。
• 在独立进程或全新持有者中构造失败场景，确认后续调用仍返回保存的错误，不会悄悄触发重试。
• 检查初始化函数的依赖是否又调用同一个 Get，避免初始化期间递归进入同一个 Once。
• 检查资源使用后是否发生更新、提前关闭或持有者复制，这些问题不由一次性初始化解决。

同一个 Once 的初始化函数如果重新进入自身 Do，会造成死锁；初始化依赖应保持单向，不能绕一圈回到资源入口。相关实现说明：https://go.dev/src/sync/once.go。

每次请求都可以新建一个 Once 吗？

可以新建对象，但它只能限制那个对象自己的动作，不能保证跨请求单例。要共享资源，必须共享同一个持有者和初始化结果。

初始化成功后资源还能改吗？

取决于资源接口。本例禁止外部拿到 map，并约定不再修改；可变资源需要自己的锁或其他同步设计，Once 不能替代它。

第一次请求取消会让初始化重试吗？

不会因为取消而自动重试。如果把请求上下文捕获进单例初始化，首次取消可能变成共享的失败结果。需要明确资源创建的上下文归属与超时策略，不要让随机首个请求决定长期资源寿命。

我的选择很明确：固定、可共享、只需一次构造的资源适合 Once；需要重连、更新、多配置或动态关闭的资源，应先设计生命周期，再选择同步工具。真正可靠的单例，不只是“只创建一次”，还要让失败结果与使用边界同样清楚。