Go sync.OnceValue 延迟初始化结果的复用方式

需要把配置、正则表或昂贵计算延迟到第一次真正使用时，通常还希望多个 goroutine 共享同一个结果。sync.OnceValue 正适合这个边界：它接收一个 func() T，返回一个可重复调用的 func() T；初始化函数只执行一次，后续调用复用已经得到的值，并且返回函数可以被并发调用。

官方资料：https://pkg.go.dev/sync

一次计算、并发调用与结果复用

最小用法是先声明一个延迟加载函数，再在业务代码里像普通函数一样调用。下面的例子把应用配置构造推迟到第一次请求，并让三个 goroutine 共享它。

package main

import (
	"fmt"
	"sync"
)

type AppConfig struct {
	Endpoint string
	Timeout  int
}

var loadConfig = sync.OnceValue(func() *AppConfig {
	// 这里模拟只应执行一次的配置构造或文件解析。
	return &AppConfig{Endpoint: "https://api.internal", Timeout: 3}
})

func main() {
	const workers = 3
	var wg sync.WaitGroup
	wg.Add(workers)
	for i := 0; i 

关键点不在于把变量声明成全局，而在于 loadConfig 是一个闭包。第一次调用时，闭包内部的函数负责生成 *AppConfig；之后每次调用都返回已经保存的指针。并发调用发生在初始化期间时，调用方会等待同一轮初始化结束，而不会各自构造一份配置。

返回结果后，哪些值会被复用

OnceValue[T] 的泛型参数决定了缓存值的类型。如果 T 是整数、字符串或只读配置结构，复用关系比较直观；如果 T 是指针、切片或 map，复用的是容器引用，调用方对其进行修改仍会影响其他调用方。

因此，OnceValue 解决的是“只初始化一次并安全发布结果”，不是“自动深拷贝结果”。如果每个请求都需要独立的可变对象，可以让闭包只缓存模板，再在调用点复制；不要把共享指针直接当作请求级工作区。

需要 error 时用 OnceValues 保留完整结果

初始化可能失败时，不建议把错误塞进一个自定义结构后再拆解。标准库提供了配套的 sync.OnceValues，可以一次缓存两个返回值，典型写法如下：

var loadRules = sync.OnceValues(func() ([]byte, error) {
	// 读取失败也会随结果一起保存，调用方无需另加锁。
	return os.ReadFile("rules.json")
})

func rules() ([]byte, error) {
	data, err := loadRules()
	if err != nil {
		return nil, fmt.Errorf("load rules: %w", err) // 保留原始错误链。
	}
	return data, nil
}

上面的片段需要导入 fmt、os 和 sync。OnceValues 同样只执行一次；如果第一次读取失败，后续调用会得到同一个 data 与 error。这适合失败后应保持故障状态的配置、规则和元数据加载，不适合必须自动重试的网络探活。

panic、重置与热更新边界

Go 官方文档明确说明：如果初始化函数 panic，返回的函数在后续调用中会使用相同的 panic 值再次 panic。这个行为能避免某个调用方看到失败、另一个调用方却继续使用半初始化结果，但也意味着“下一次调用自动重试”不是 OnceValue 的语义。

同样，OnceValue 没有 Reset 方法。需要按租户、配置版本或时间窗口重新加载时，应把版本选择放在 OnceValue 外面，例如用带版本的 map、原子指针或显式的读写锁管理生命周期；不要通过重新赋值全局闭包来掩盖并发切换问题。初始化函数还应尽量避免反向调用自身，否则容易形成递归或等待链。

常见问题

OnceValue 会为每个 goroutine 生成独立结果吗？

不会。它协调同一个返回函数的初始化，并复用一次调用得到的 T；T 如果是指针，调用方拿到的是同一个指针。

初始化失败后如何自动重试？

不要直接依赖 OnceValues。把重试策略放到外层状态机或带过期时间的缓存中，成功后再用 OnceValue 固定结果。

OnceValue 能替代所有 sync.Once 吗？

不能。只关心副作用、不需要返回值时使用 OnceFunc 或 sync.Once；需要一个返回值时才选择 OnceValue。

实际落地时，可以先问清楚三个问题：结果是否允许共享、失败是否应该永久复用、是否需要重置。三个答案都明确后，OnceValue 才会成为清晰的生命周期边界，而不是隐藏状态的容器。