sync.OnceValues用于延迟加载可能失败的资源，支持返回(T, error)，首次调用执行初始化函数并缓存结果（含error），后续直接返回缓存值；并发安全，不重试、不panic，需显式返回error而非内部panic。
sync.OnceValues 用来处理带 error 的初始化
当你需要延迟加载一个可能失败的资源（比如读文件、连数据库、解析配置），sync.OnceValue 不够用——它只接受 func() T，没法返回 error。Go 1.21 同时引入了 sync.OnceValues，专为这种场景设计：它支持初始化函数返回任意数量的值，包括 error。
-
sync.OnceValues的签名是func OnceValues[T any, E error](f func() (T, E)) func() (T, E)，泛型约束明确要求第二个返回值必须是error - 它返回的闭包，首次调用时执行
f，缓存其全部返回值（含error）；后续调用直接返回缓存结果，不重试、不重新 panic - 和
sync.OnceValue一样，并发安全，多个 goroutine 同时调用也只执行一次f
常见错误：把错误处理逻辑塞进闭包里再 panic
有人会写类似这样的代码：
loadConfig := sync.OnceValues(func() (map[string]string, error) {
cfg, err := os.ReadFile("config.yaml")
if err != nil {
panic(err) // ❌ 错误：panic 会导致程序崩溃，且 done 被设为 1，后续调用永远拿不到 error
}
return parse(cfg), nil
})
这违反了 sync.OnceValues 的设计前提：它依赖函数正常返回 (T, error) 来区分成功与失败。一旦 f panic，整个 goroutine 崩溃，done 仍被原子设为 1，后续所有调用都卡死或 panic，无法 fallback。
- 正确做法是让
f显式返回error，而不是 panic - 如果底层库（如
sql.Open）本身不 panic，就直接返回；如果它可能 panic，需在外层 recover 并转为 error - 不要在
f内部做重试——OnceValues不重试，失败即永久失败
实际使用：读配置文件并解析
这是最典型的 sync.OnceValues 使用场景：
立即学习“go语言免费学习笔记（深入）”；
package main
import (
"encoding/json"
"fmt"
"os"
"sync"
)
type Config struct {
DBHost string `json:"db_host"`
Port int `json:"port"`
}
var loadConfig = sync.OnceValues(func() (Config, error) {
data, err := os.ReadFile("config.json")
if err != nil {
return Config{}, fmt.Errorf("failed to read config: %w", err)
}
var cfg Config
if err := json.Unmarshal(data, &cfg); err != nil {
return Config{}, fmt.Errorf("failed to parse config: %w", err)
}
return cfg, nil
})
func GetConfig() (Config, error) {
return loadConfig()
}
- 首次调用
GetConfig()会触发文件读取和 JSON 解析；失败时返回具体error，成功则缓存Config实例 - 后续调用直接返回缓存值或上次的 error，无锁、无 IO、无解析开销
- 注意：
os.ReadFile返回的是[]byte，不是string，别误写成os.ReadFull或漏掉错误检查
容易忽略的点：OnceValues 不区分“未执行”和“执行失败”
sync.OnceValues 返回的闭包没有状态查询接口。一旦你调用过它，你就无法知道当前缓存的是成功结果还是失败的 error —— 它只管返回上次 f 的完整返回值。
- 这意味着：如果第一次调用返回
(Config{}, io.EOF)，之后所有调用都返回这个io.EOF，哪怕文件后来被修复了 - 它不适合需要自动重试或健康检查的场景（比如 DB 连接池保活），这类需求得自己封装状态机 + 定时器
- 如果你需要区分“还没开始”、“执行中”、“成功”、“失败”，就得回到手写
sync.Once+ 多个变量的老路
