Go 一次性初始化结果怎么缓存：错误传播、并发读取与测试边界

服务启动时有一段配置加载很慢，最容易出现的补丁是给全局变量加一把锁，再自己维护“是否初始化”的布尔值。Go 1.21 的 sync.OnceValue 把这件事收成了一个函数：第一次调用执行初始化，后续调用直接拿同一个结果，而且返回函数可以被多个 goroutine 同时调用。

并发请求为什么只应该触发一次初始化

假设每个请求都要读取一份只读规则。规则来源可能是文件、环境变量或远端配置，但进程内只需要成功得到一份快照。把初始化函数包进 sync.OnceValue 后，调用方不需要知道锁和状态位在哪里。

package main

import (
    "fmt"
    "sync"
)

func loadRules() map[string]string {
    fmt.Println("load rules")
    return map[string]string{"region": "cn-east"}
}

var rules = sync.OnceValue(loadRules)

func handleRequest() string {
    return rules()["region"]
}

handleRequest 可以由多个 goroutine 调用。第一次真正进入 loadRules，之后调用只返回已经保存的 map。这里的 map 如果只读就足够安全；若业务会修改内容，应该在初始化时构造不可变快照，或返回副本，不能把 OnceValue 当成容器并发保护。

OnceValue 的缓存边界：值、错误和 panic 都要看清

只返回一个值时，用 OnceValue

它的函数签名是 func OnceValue[T any](f func() T) func() T。没有参数，也没有显式错误位，因此适合“初始化失败就让调用方无法继续”的场景，例如固定格式的内置表、进程启动后必需的解析结果。

需要错误时，用 OnceValues

文件读取、配置解析这类操作通常需要保留错误。OnceValues 可以把一对返回值一起缓存：

var config = sync.OnceValues(func() (*Config, error) {
    data, err := os.ReadFile("config.toml")
    if err != nil {
        return nil, err
    }
    cfg, err := parseConfig(data)
    return cfg, err
})

cfg, err := config()
if err != nil {
    // 后续调用仍会看到同一个初始化错误
    return err
}

这意味着“第一次读文件失败，第二次恰好文件恢复”并不会自动重试。这个结果不是 bug，而是 OnceValues 的语义：初始化函数只运行一次，返回值和错误都成为这次初始化的最终快照。

不要把临时网络故障永久缓存

数据库连接、服务发现或带过期时间的远端配置，通常需要重试、刷新和熔断。此时可以把 OnceValue 只用于初始化一个带刷新能力的客户端，而不是缓存某次网络请求的结果。边界判断很简单：结果是否能在进程生命周期内视为稳定值？如果不能，就应选择带状态转换的缓存或重试策略。

Go 1.21 版本与测试写法

OnceFunc、OnceValue 和 OnceValues 是 Go 1.21 新增的同步工具。项目的 go.mod 版本低于 1.21 时，代码会在编译阶段暴露问题，不要用运行时判断来掩盖版本不匹配。

module example.com/rules

go 1.21

测试时不要复用生产包级变量。OnceValue 返回的是带内部状态的闭包，一个测试先调用过，后面的测试就无法再次进入初始化函数。把构造函数单独抽出，每个用例都拿一个新的闭包：

func newRules(load func() (map[string]string, error)) func() (map[string]string, error) {
    return sync.OnceValues(load)
}

func TestRulesOnlyLoadOnce(t *testing.T) {
    calls := 0
    get := newRules(func() (map[string]string, error) {
        calls++
        return map[string]string{"region": "cn-east"}, nil
    })

    _, _ = get()
    _, _ = get()
    if calls != 1 {
        t.Fatalf("load calls = %d, want 1", calls)
    }
}

如果测试会并发调用，再配合 go test -race ./... 检查调用方是否修改了返回对象。OnceValue 只负责一次性同步，不替你解决返回对象的可变性。

上线前的三个判断

最后再检查一次初始化函数是否有副作用、返回对象是否会被修改，以及测试是否为每个用例重新建闭包。三个答案都明确后，OnceValue 才是简化状态管理，而不是把问题藏进闭包。

常见问题

OnceValue 能在初始化失败后重试吗？

不能。若初始化函数通过 OnceValues 返回错误，这个错误会随结果一起缓存。需要重试时，应使用明确的重试或刷新机制。

OnceValue 返回的 map 可以直接修改吗？

OnceValue 本身不保护 map 的后续读写。共享 map 只读才安全；要修改请返回副本，或使用其他同步方案。

OnceValue 和 sync.Once 有什么区别？

sync.Once 只保证一个动作执行一次，结果和错误需要你自己保存；OnceValue/OnceValues 直接把返回值封装进一次性函数，调用方更简单。

为什么测试用例之间会互相影响？

返回函数内部带有执行状态。包级闭包一旦被某个测试调用，后续测试拿到的就是已缓存结果，所以应该为每个测试重新构造。

小结

sync.OnceValue 解决的是“稳定结果只初始化一次”，sync.OnceValues 进一步把错误纳入同一份快照。它们让并发读取更直接，但不会替你决定结果是否应该过期，也不会保护返回对象的可变状态。先确认生命周期，再选择一次性闭包，代码才会真正变简单。