Go 一次性值函数怎么缓存计算：惰性初始化、错误值与并发边界

服务启动后第一次读取远程配置，最容易把“只做一次”写成共享变量、互斥锁和错误分支。Go 1.21 的 sync.OnceValue 把这件事收成一个可并发调用的函数：第一次调用负责计算，后续调用直接拿同一个结果。它适合配置快照、规则表、编译后的正则等只需要初始化一次的值。

先把首次加载收成一个并发安全入口

假设服务要加载一份不会在进程内修改的路由规则。OnceValue 直接把工厂函数包起来，调用方只看到一个普通的 func() T。

var routes = sync.OnceValue(func() RouteTable { fmt.Println("load route table"); return RouteTable{Version: "2026-08", Rules: []string{"/health", "/orders", "/reports"}} })
first := routes()
second := routes()
fmt.Println(first.Version == second.Version)

运行时只会打印一次 load route table。初始化函数的调用次数和发布后的读取边界都被固定了；读者拿到的是值副本，规则切片仍然要按不可变数据来使用。

上线前先核对工具链和初始化函数职责

OnceValue 在 Go 1.21 加入。生产代码不要只看本机版本：构建机、容器镜像和 go.mod 的 go 行都要满足它。可按顺序执行 go version、go env GOTOOLCHAIN 和 go list -m 做核对。

初始化函数只做一次性计算，不要把请求上下文、用户身份或每次变化的参数藏进去。若结果依赖租户、语言或请求头，就把参数显式放到普通函数中，否则第一次请求会决定整个进程的结果。

需要错误时，把成功值和失败值一起锁定

OnceValue 的签名只有一个返回值。工厂函数可能失败时，使用 sync.OnceValues 比把错误写进外部变量更直接。

var loadConfig = sync.OnceValues(func() (RouteTable, error) {
    data, err := readRouteFile("routes.json")
    if err != nil { return RouteTable{}, err }
    return parseRoutes(data)
})

无论多少个 goroutine 同时调用，读取和解析都只发生一次；首次结果是错误时，后续调用也会看到同一个错误。这适合配置缺失就进入明确失败状态的服务，不适合文件稍后出现、需要自动重试的任务。

panic 会被记住，别把它当成重试机制

官方文档说明：工厂函数 panic 后，返回函数后续调用仍会以同一个值 panic。配置损坏时不能靠下一次调用碰巧恢复。

var mustRules = sync.OnceValue(func() []string {
    rules, err := readRules()
    if err != nil { panic(err) }
    return rules
})

只有初始化失败就必须终止进程时才考虑这种写法。大多数服务更适合在启动阶段显式调用一次、记录错误并退出，或者使用 OnceValues 让上层决定降级和告警。

并发验收要看只执行一次

测试时给工厂函数增加原子计数器，再从多个 goroutine 同时调用。若项目尚未使用支持 WaitGroup.Go 的工具链，就用 Add、go func 和 Done，测试目标不变。

var calls atomic.Int32
value := sync.OnceValue(func() int { calls.Add(1); return 42 })
var wg sync.WaitGroup
for range 20 { wg.Go(func() { _ = value() }) }
wg.Wait()
if got := calls.Load(); got != 1 { t.Fatalf("factory calls = %d", got) }

并发验收还要检查工厂返回的数据是否被调用方修改；OnceValue 只负责初始化同步，不会保护返回对象内部的可变字段。

相关问题

OnceValue 和 OnceFunc 怎么选？

没有返回值用 OnceFunc；缓存一个值用 OnceValue；同时缓存值和错误用 OnceValues。

OnceValue 能手动清空缓存吗？

不能。需要热更新时，把版本或实例放在外层，通过原子替换、读写锁或显式缓存管理生命周期。

返回切片会自动变成只读吗？

不会。切片、map 和指针内部仍可能被修改；共享结果应在初始化时构造不可变快照。

Go 1.20 项目能直接调用 OnceValue 吗？

不能直接调用不存在的标准库 API。先升级工具链和 go.mod，或用 sync.Once 封装兼容实现。

发布前的最小检查清单

• 初始化函数不依赖请求参数，返回结果不会被继续写入。
• 可能失败的读取使用 OnceValues，明确失败后的重启或修复策略。
• 用竞态检测和并发测试确认工厂只运行一次。
• 所有构建环境满足 Go 1.21 或更高版本。

sync.OnceValue 不是通用缓存，也不会替你设计热更新。把“一次性、无参数、结果可复用”三个条件核对清楚，再把它放进代码，并发行为才会稳定。