借助 OnceValue 延迟构造共享配置并传播初始化错误

服务启动后，多个 goroutine 都会读取同一份配置。最初的实现把 sync.Once、*Config 和 error 放成三个包级变量：功能能跑，但调用者很容易只拿配置、忘记检查初始化错误，测试也会被已经执行过的 Once 污染。

Go 1.21 引入了 sync.OnceValue、sync.OnceValues。前者缓存一个返回值；配置加载通常返回 (*Config, error)，所以本文实际使用同一家族里能缓存两个返回值的 OnceValues。官方文档：https://pkg.go.dev/sync

问题现场：重复加载与错误状态开始分叉

假设 HTTP 处理器第一次用到配置时才读取 JSON。直接调用 loadConfig 会重复做文件 I/O；改成传统 Once 后，代码常变成下面这样：

var (
    configOnce sync.Once
    sharedCfg  *Config
    initErr    error
)

func SharedConfig() (*Config, error) {
    // 三份外部状态必须始终一起维护
    configOnce.Do(func() {
        sharedCfg, initErr = loadConfig("config.json")
    })
    return sharedCfg, initErr
}

这段代码线程安全，却有两个工程问题：状态契约散落在闭包外；包级 Once 无法在测试之间恢复零值。若又增加热更新、环境变量覆盖或多租户路径，调用关系会越来越难隔离。

初步判断：OnceValue 只能装一个返回值

sync.OnceValue 的签名是 func(func() T) func() T，适合只返回配置值的纯构造。为了保留 Go 惯用的显式错误，不能丢掉 error，也不必额外定义 Result 包装结构；直接使用 sync.OnceValues，让配置与错误成为不可拆分的一对结果。

官方定义还明确了两个语义：返回函数可被并发调用；如果初始化函数 panic，之后每次调用都会用同一个值再次 panic。因此它是“一次决定，永久复用”，而不是失败后自动重试。

动手修复：构造一个可隔离的 ConfigProvider

把路径作为构造参数，把 Once 状态藏进返回闭包。生产环境可以保存一个 provider，测试则为每个用例新建 provider：

package config

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

type Config struct {
    APIBaseURL string `json:"api_base_url"`
    TimeoutMS  int    `json:"timeout_ms"`
}

type Provider func() (*Config, error)

func NewProvider(path string) Provider {
    // 配置与错误由同一个闭包一次性缓存
    return sync.OnceValues(func() (*Config, error) {
        data, err := os.ReadFile(path)
        if err != nil {
            return nil, fmt.Errorf("读取配置: %w", err)
        }

        var cfg Config
        if err := json.Unmarshal(data, &cfg); err != nil {
            return nil, fmt.Errorf("解析配置: %w", err)
        }
        if cfg.APIBaseURL == "" {
            return nil, errors.New("api_base_url 不能为空")
        }
        return &cfg, nil
    })
}

应用只需要在组装依赖时创建一次：

var sharedConfig = config.NewProvider("config.json")

func handleRequest() error {
    // 每个调用者都必须同时接收配置和初始化错误
    cfg, err := sharedConfig()
    if err != nil {
        return fmt.Errorf("配置不可用: %w", err)
    }
    _ = cfg // 在业务逻辑中使用只读配置
    return nil
}

这里没有额外锁，也没有“先判断 cfg 是否为 nil”的双重检查。并发协调和结果发布都由 OnceValues 负责。配置对象发布后应视为只读；如果其他 goroutine 继续修改其中的 map 或 slice，OnceValues 并不会替你解决数据竞争。

验证结果：成功与失败都会稳定复用

为了验证“只调用一次”而不碰文件系统，可以再抽象加载函数：

func NewProviderWithLoader(
    load func() (*Config, error),
) Provider {
    // 测试可注入带计数器的加载函数
    return sync.OnceValues(load)
}

并发测试只需让多个 goroutine 调用同一个 provider，并用原子计数器记录加载次数：

func TestProviderLoadsOnce(t *testing.T) {
    var calls atomic.Int32
    provider := NewProviderWithLoader(func() (*Config, error) {
        // 无论有多少并发调用，这里都应只执行一次
        calls.Add(1)
        return &Config{APIBaseURL: "https://api.example"}, nil
    })

    var wg sync.WaitGroup
    for i := 0; i 

把加载器改成返回固定错误，同样可以验证 32 个调用者拿到错误，而计数仍为 1。错误不会被吞掉，但也不会自动重试。

定位边界：哪些初始化不该交给 OnceValues

• 瞬时错误需要重试：网络抖动、临时凭据服务不可用等失败会被永久缓存，应使用带互斥状态、退避与明确失效策略的组件。
• 请求级 context：不要让第一个请求的取消或超时决定整个进程的配置结果。进程级配置应使用独立生命周期，或在服务接流量前完成初始化。
• 需要热更新：OnceValues 没有 Reset。可将不可变配置放进 atomic.Pointer，由独立刷新器校验后整体替换。
• 构造会 panic：panic 会在后续调用中重复出现。可预期的配置问题应转换为 error，而不是依赖 recover 继续服务。

常见问题

为什么标题写 OnceValue，代码却是 OnceValues？

OnceValue 是这组“把一次初始化包装成返回函数”API 的单值版本。传播配置与错误需要两个返回值，因此应选 OnceValues；如果构造永不失败，只返回 *Config，才直接用 OnceValue。

初始化失败后能删除配置文件再重试吗？

不能。第一次返回的 error 已经被缓存。需要重试时应重新创建 provider，或采用有显式状态和退避规则的可重试加载器。

多个调用者拿到的是同一个配置指针吗？

是。闭包只执行一次，之后返回缓存的同一对值。因此配置最好不可变；需要更新时应发布一份新的完整快照。

总结

排查这类共享配置问题的关键，不只是“只初始化一次”，而是让值与错误始终作为同一契约传播。Go 1.21+ 中，单值构造用 OnceValue，(*Config, error) 用 OnceValues。再把它封装成可按实例创建的 provider，就能同时获得并发安全、延迟加载、错误一致性和测试隔离；代价则是首个结果永久缓存，不适合重试与热更新。