Go sync.OnceValue 返回的函数为什么不适合返回可变全局

sync.OnceValue 解决的是“初始化函数只执行一次，并把结果缓存下来”，不是“每次调用都得到一个新的对象”。如果结果类型是指针、map、slice，或者结构体内部含有这些可变成员，那么多个调用者拿到的就是同一份底层状态。初始化阶段虽然由 OnceValue 负责并发协调，初始化完成后的读写仍然要由对象自己负责。

把 OnceValue 返回的对象当成只读快照最稳妥；如果它必须变化，就让对象内部持有锁，或者在缓存的基础上为每次调用复制一份，而不要把原始可变全局直接暴露出去。

OnceValue 缓存的是结果，不是创建逻辑

官方定义是 OnceValue[T](f func() T) func() T：返回的函数会调用 f 一次并返回它的结果，而且这个返回函数可以被并发调用。源码中，结果被保存到闭包状态的 result 字段，后续调用直接返回这个字段。

因此下面的初始化函数只负责创建一次 *Config，loadConfig() 也不会在第二次调用时重新执行：

var getConfig = sync.OnceValue(func() *Config {
	// 初始化只发生一次，返回的指针会被缓存。
	return loadConfig()
})

func handler() {
	cfg := getConfig()
	// 这里拿到的是缓存指针，不是新的 Config 副本。
	_ = cfg.Timeout
}

这与返回整数、字符串等值类型的情况不同。值类型通常可以直接当作只读结果使用；引用到共享底层存储的类型则要继续追踪所有权。

指针、map 和 slice 会把可变状态带出去

最容易误判的是“函数返回值看起来每次都重新赋给了局部变量”。局部变量只是复制了指针或 slice/map 描述符，并没有复制它们指向的底层对象。

type FeatureSet struct {
	Flags map[string]bool
}

var features = sync.OnceValue(func() *FeatureSet {
	// map 只创建一次，后续调用共享同一个 map。
	return &FeatureSet{Flags: map[string]bool{"new-ui": true}}
})

func enableForTest() {
	set := features()
	// 这次写入会改变所有后续调用者看到的共享状态。
	set.Flags["debug"] = true
}

func readFeature() bool {
	// 这里读到的是 enableForTest 写入后的同一个 map。
	return features().Flags["debug"]
}

如果多个 goroutine 同时读写这个普通 map，还会进入 Go map 的并发访问风险；OnceValue 并不会把返回对象自动变成并发安全容器。slice 也类似：复制 slice 只复制长度、容量和数据指针，元素仍可能共享同一数组。

结构体按值返回也不等于深拷贝。例如 struct{ Items []string } 的结构体副本仍然可能共享 Items 的底层数组。判断边界时要看“可变成员最终归谁所有”，不能只看函数签名是否带指针。

三种封装方式对应三种所有权

确定结果确实只读时，可以继续使用 OnceValue，但最好把可变成员藏在未导出字段中，只提供返回标量或不可变视图的方法。这样缓存的对象是一次性构建的只读快照。

如果对象必须长期变化，就让同步责任跟着对象走，而不是让每个调用方自行记住一把外部锁：

type Registry struct {
	mu    sync.RWMutex
	items map[string]string
}

var registry = sync.OnceValue(func() *Registry {
	// 初始化一次容器；后续的并发读写由 Registry 自己保护。
	return &Registry{items: make(map[string]string)}
})

func (r *Registry) Put(key, value string) {
	r.mu.Lock()
	defer r.mu.Unlock() // 确保所有返回路径都释放写锁。
	r.items[key] = value
}

func (r *Registry) Get(key string) (string, bool) {
	r.mu.RLock()
	defer r.mu.RUnlock() // 读操作与 Put 使用同一套保护。
	value, ok := r.items[key]
	return value, ok
}

另一种需求是“基础配置只加载一次，但每个请求都要有自己的可变副本”。此时把缓存层和复制层分开：

var baseConfig = sync.OnceValue(loadConfig)

func NewConfig() Config {
	base := baseConfig()
	copy := base
	// map 成员必须单独复制，避免调用者改到缓存对象。
	copy.Labels = make(map[string]string, len(base.Labels))
	for key, value := range base.Labels {
		copy.Labels[key] = value
	}
	return copy
}

这个模式只保证示例中的 map 被复制；如果结构体还有指针、slice、嵌套 map 等成员，也必须按实际数据结构继续复制。复制本身也有成本，不能把它当成无条件的性能优化。

发布前用这张表检查初始化边界

最后还要记住一个细节：如果初始化函数 panic，OnceValue 的返回函数后续调用会以相同值再次 panic。它适合表达“初始化失败就让所有调用看到同一失败结果”的语义，但这同样不等于对象初始化后可以随意并发修改。

相关问题

OnceValue 和 sync.Once 的主要区别是什么？ sync.Once 只负责执行动作，结果通常需要外部变量保存；OnceValue 把结果缓存和返回函数组合在一起。

返回 slice 时复制 slice 头够不够？ 不够。复制头部仍可能共享底层数组；如果调用者要独立修改，需要复制元素，嵌套引用还要继续复制。

给 OnceValue 返回的对象加一把全局锁可以吗？ 可以，但锁和对象的所有读写必须形成统一约定。更容易维护的做法通常是让对象的方法内部持有并使用自己的锁。