Go 一次性值函数如何缓存初始化结果：惰性构造与并发读取

配置加载、正则编译和只读客户端创建，通常不值得在服务启动时全部完成：有些请求永远不会走到对应分支。但把初始化函数直接放进每次请求路径，又会让并发请求重复构造对象。Go 1.21 加入的 sync.OnceValue 把这两个要求接到了一起：第一次真正调用时执行初始化，之后返回同一个结果，而且返回函数可以被多个 goroutine 并发调用。

为什么把初始化放进请求路径

假设服务只有少量请求会使用订单号校验器。启动阶段直接编译正则，所有实例都会付出成本；每次请求重新编译，又失去了共享和并发安全。更合适的边界是保存“如何构造”的函数，而不是提前保存一个可能尚未使用的对象。

OnceValue 的类型签名是 func OnceValue[T any](f func() T) func() T。这里的泛型 T 由工厂函数返回值推导，调用方拿到的是一个无参数函数。它没有 reset 方法，也不接受新的工厂函数，这正好表达“一个生命周期内只初始化一次”。

第一次调用如何完成初始化并缓存结果

下面的例子把昂贵动作收进 buildValidator，但不在创建 validator 时执行它。第一次 validator() 进入 sync.OnceValue，工厂函数返回 *regexp.Regexp；后续调用只读取已经保存的结果。

package main

import (
    "fmt"
    "regexp"
    "sync"
)

func buildValidator() *regexp.Regexp {
    fmt.Println("compile validator")
    return regexp.MustCompile(`^ORD-[0-9]{8}$`)
}

func main() {
    validator := sync.OnceValue(buildValidator)
    fmt.Println(validator().MatchString("ORD-20260827"))
    fmt.Println(validator().MatchString("bad-order"))
}

运行时只会打印一次 compile validator，而两个匹配动作都使用同一个正则对象。注意，validator := sync.OnceValue(buildValidator) 这一行本身没有调用 buildValidator；测试惰性行为时，计数器应该放在真正的 validator() 之后观察。

并发读取时需要关注哪条边界

返回函数可以被并发调用，但这不等于工厂函数可以随意访问共享可变状态。初始化期间由 OnceValue 负责只执行一次，工厂函数内部仍然要遵守普通的数据竞争规则。初始化完成后，返回的对象也必须适合并发读取；例如只读的 *regexp.Regexp 可以共享，而带有未保护写入的自定义结构体不应仅凭 OnceValue 获得安全保证。

var validator = sync.OnceValue(func() *regexp.Regexp {
    return regexp.MustCompile(`^ORD-[0-9]{8}$`)
})

func checkOrder(id string) bool {
    return validator().MatchString(id)
}

这个调用链可以概括为：checkOrder 调用 validator，validator 只在首次访问时构造对象，之后把缓存的 *regexp.Regexp 返回给每个请求。不要在 checkOrder 里修改共享对象的字段，也不要用重新赋值的方式实现“刷新”；需要刷新就应该设计新的生命周期或显式版本化。

初始化 panic 为什么不会自动重试

很多人把“一次性初始化”理解成“失败后再来一次”。OnceValue 的语义不是这样：如果 f panic，返回函数后续调用会用同一个值再次 panic。这能避免并发调用者看到一部分初始化结果，也能让配置损坏这类不可恢复问题保持显式失败。

func loadConfig() map[string]string {
    panic("config missing")
}

config := sync.OnceValue(loadConfig)
// config() 第一次 panic("config missing")
// config() 后续调用仍然 panic("config missing")

如果业务确实需要重试，工厂函数里要明确实现重试，或把状态机放在更高一层；不要期待重新调用闭包会重新执行 loadConfig。对于可以恢复的外部错误，sync.OnceValues 更适合把 value 和 error 一起缓存，再由调用方决定如何处理错误。

OnceValue、OnceValues 和手写 Once 怎么选

手写 sync.Once 并没有天然更快。它通常需要额外的结果字段、错误字段和闭包捕获；当需求就是“调用一次得到一个值”时，OnceValue 让这个约束直接出现在类型里。真正需要测量时，再用基准测试比较完整调用路径，不要只比较一行函数调用。

测试时把“没调用”和“只调用一次”分开验证

一个可靠测试至少检查三件事：创建闭包时工厂没有运行；并发调用后计数为 1；所有调用者拿到的是同一个逻辑结果。示例中的计数器只用于测试，不要把无保护计数器放进生产工厂。

func TestOnceValue(t *testing.T) {
    var calls atomic.Int32
    value := sync.OnceValue(func() string {
        calls.Add(1)
        return "ready"
    })

    if got := calls.Load(); got != 0 { t.Fatal(got) }
    if value() != "ready" || value() != "ready" { t.Fatal("unexpected value") }
    if got := calls.Load(); got != 1 { t.Fatalf("calls=%d", got) }
}

再补一条 go test -race 检查，确认工厂和返回对象本身没有竞争。这个命令只能发现测试路径实际触发的竞争，不能替代对对象生命周期的设计判断。

相关问题

OnceValue 是启动时执行还是第一次调用时执行？

是第一次调用时执行。创建返回闭包的语句不会触发工厂函数。

初始化函数返回错误时能否直接用 OnceValue？

可以把错误包在自定义结果里，但通常应优先考虑 sync.OnceValues，让值和错误一起成为一次性结果。

OnceValue 能否清空缓存重新初始化？

不能。需要刷新时，创建新的闭包并用明确的版本或生命周期管理它。

OnceValue 能保证返回对象的所有操作都并发安全吗？

不能。它只保证初始化动作的一次性与调用间同步；对象后续的读写仍要遵守该对象自己的并发规则。

把 OnceValue 放在“惰性、只读、同一生命周期只构造一次”的边界内，代码通常会比一组分散的 sync.Once、结果字段和错误字段更容易复查。若初始化需要重试、过期刷新或租约更新，就把这些状态显式建模，不要把一次性闭包当成通用缓存。