Go 语言里的 sync.OnceValue：把懒加载写得更直接

花开有时

发布时间：2026-08-25 | 133人浏览过

原创

前言

在 Go 项目里，配置读取、数据库连接初始化、重计算缓存这类逻辑，常常都带着两个要求：只执行一次，以及后续能重复拿结果。过去用 sync.Once 能解决“只执行一次”，但返回值还得额外放到外层变量里。Go 1.21 引入的 sync.OnceValue，正是为这类懒加载场景补上最后一块拼图：既保证只执行一次，也把结果缓存和返回动作一起封装起来，让你更容易判断它是否适合替换现有写法。

为什么要用 sync.OnceValue

先看传统 sync.Once 的常见写法：

对比传统 sync.Once 和 sync.OnceValue 的结果缓存方式 — **从外部变量到结果内聚**把“只执行一次”和“结果缓存”放在同一张专栏卡片里，适合解释为什么新接口更顺手。

var (
    config map[string]string
    once   sync.Once
)

func GetConfig() map[string]string {
    once.Do(func() {
        // 从文件或远程加载配置
        fmt.Println("Loading config...")
        config = make(map[string]string)
        config["host"] = "127.0.0.1"
        config["port"] = "8080"
    })
    return config
}

这类代码的问题不在功能，而在组织方式。初始化逻辑写在 once.Do 里，结果却要额外放到外层变量中保存。只要是“执行一次并复用结果”的模式，代码通常都会多出一层状态声明，读起来也不够直接。

sync.OnceValue 的意义就在这里：它把“单次执行”和“结果缓存”绑定在一起，调用者拿到的是一个函数，第一次调用时完成计算，后续调用直接返回缓存值。对于懒加载配置、单例资源、昂贵计算结果复用这样的场景，写法会更紧凑，也更接近业务意图。

sync.OnceValue 是什么，返回了什么

sync.OnceValue 是 Go 1.21 新增能力，核心思路很简单：传入一个会返回值的函数，再得到一个“只会真正执行一次”的新函数。

func OnceValue(f func() T) func() T

它的行为可以概括成两步：

首次调用返回函数时，执行 f 并记录结果
后续再次调用时，直接返回第一次得到的值，不再重复执行 f

和 sync.Once 相比，最大的变化不是并发模型，而是 API 形态。以前你要自己管理缓存变量；现在缓存结果就是这个返回函数的一部分。也因此，代码在表达上会更像“声明一个懒加载值”，而不是“声明一个 once，再额外维护一个结果容器”。

怎么用：基础场景与并发调用

基础用法

package main

import (
    "fmt"
    "sync"
)

func main() {
    // 创建一个只会执行一次的计算函数
    calculate := sync.OnceValue(func() int {
        fmt.Println("Start complex calculation")
        sum := 0
        for i := 0; i < 1000000; i++ {
            sum += i
        }
        return sum
    })

    // 多次调用，但只会计算一次
    fmt.Println("Result:", calculate())
    fmt.Println("Result:", calculate()) // 这次不会重新计算
}

这个例子最适合用来理解它的行为。calculate 本身不是计算结果，而是一个包装后的函数。第一次调用 calculate() 时，会打印 Start complex calculation 并完成求和；第二次调用仍然返回同样的结果，但不会再执行那段循环。

sync.OnceValue 与 OnceValues 在并发和错误返回中的调用路径示意 — **并发汇聚与结果复用**用不同卡片组织方式展示并发调用如何汇聚到一次执行，以及错误返回如何被缓存。

这意味着，只要你的逻辑天然符合“第一次算，后面复用”的模式，就可以直接把原本的初始化代码包进 sync.OnceValue。

并发下是否安全

这是 sync.OnceValue 的另一个关键点：它和 sync.Once 一样，天然适用于多 goroutine 并发访问。

sync.Once 与 sync.OnceValue 在 panic 和性能上的差异总结 — **边界行为与调用成本**把最容易忽略的 panic 语义和调用开销放在同一张总结图里，方便快速判断边界。

package main

import (
    "fmt"
    "sync"
)

func main() {
    calculate := sync.OnceValue(func() int {
        fmt.Println("Start complex calculation")
        sum := 0
        for i := 0; i < 1000000; i++ {
            sum += i
        }
        return sum
    })

    // 并发调用
    var wg sync.WaitGroup
    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            fmt.Println("Result:", calculate())
        }()
    }
    wg.Wait()
}

这里虽然有 5 个 goroutine 同时调用 calculate()，但真正的计算逻辑仍然只会执行一次。其余调用会等待首次计算完成，然后拿到同一个缓存结果。

因此，在高并发环境下，它很适合用来封装：

配置或密钥读取
单例客户端初始化
代价较高但结果稳定的计算

如果你的需求只是“一次初始化，多处复用”，那它比手写 sync.Once + 外部变量 更省代码，也更不容易把状态拆散。

有错误返回怎么办：用 OnceValues

很多实际业务函数并不只返回一个值，还会返回一个 error。比如文件读取、数据库查询、远程配置拉取，这种情况下 Go 1.21 还提供了配套的 sync.OnceValues。

func OnceValues(f func() (T1, T2)) func() (T1, T2)

典型写法如下：

package main

import (
    "fmt"
    "os"
    "sync"
)

func main() {
    // 只读取一次文件
    readFile := sync.OnceValues(func() ([]byte, error) {
        fmt.Println("Reading file")
        return os.ReadFile("config.json")
    })

    // 并发读取
    var wg sync.WaitGroup
    for i := 0; i < 3; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            data, err := readFile()
            if err != nil {
                fmt.Println("Error:", err)
                return
            }
            fmt.Println("File length:", len(data))
        }()
    }
    wg.Wait()
}

这个接口的价值在于，它没有破坏 Go 常见的 (value, error) 返回模式。你不需要为了“一次执行”再额外包装结构体，也不需要单独存一个错误变量。第一次执行得到的返回值和错误，都会被后续调用复用。

不过这里也带来一个很实际的判断标准：如果初始化失败后你希望“下一次调用再重试”，那 OnceValues 未必适合。因为它缓存的不只是成功值，第一次返回的错误结果同样会被保留下来。