Go sync.OnceFunc 包装的函数 panic 后再次调用会怎样

sync.OnceFunc 包装的函数如果第一次执行时发生 panic，底层函数不会再次执行，但包装后返回的函数以后每次被调用都会使用同一个 panic 值再次 panic。它不是“失败后重试一次”，也不是“只在第一次调用时 panic”。

官方文档：https://pkg.go.dev/sync#OnceFunc

标准库源码：https://go.dev/src/sync/oncefunc.go

一次执行的是被包装函数 f；重复发生的是包装函数向调用者抛出的 panic。两件事必须分开理解。

panic 会被记住并在每次调用时重放

sync.OnceFunc(f) 返回一个新的无参数函数。无论这个返回函数被串行调用还是并发调用，f 最多只执行一次。若 f 正常返回，后续调用直接正常返回；若 f panic，OnceFunc 会记住 panic 值，后续调用继续用这个值 panic。

从标准库实现可以看出，它内部保存了 panic 值和一个表示执行是否成功的状态。只有 f 正常返回，成功状态才会设为真。失败后，sync.Once 仍保证 f 不再运行，但返回函数看到失败状态就会再次 panic。

第一次调用有一个额外细节：标准库会在 f 的调用现场立即重新 panic，使首次调用的堆栈能够包含 panic 的原始位置。后续调用不会重新进入 f，因此新的堆栈主要反映当前调用包装函数的位置，但 panic 值仍与第一次相同。

用最小示例观察调用次数和 panic 值

下面用计数器记录底层函数执行次数，再对包装函数调用两次。每次调用都放在独立的 recover 边界中，否则第一次 panic 会直接中断当前调用链，第二次调用没有机会发生。

package main

import (
	"fmt"
	"sync"
)

func callAndReport(label string, f func()) {
	// 每次调用都建立独立恢复边界，便于观察重复 panic。
	defer func() {
		if p := recover(); p != nil {
			fmt.Printf("%s recovered: %v\n", label, p)
		}
	}()

	f()
}

func main() {
	calls := 0

	wrapped := sync.OnceFunc(func() {
		// 这个函数体无论调用 wrapped 多少次都只会进入一次。
		calls++
		panic("configuration is invalid")
	})

	// 两次调用都会 panic，但底层函数的计数只增加一次。
	callAndReport("first", wrapped)
	callAndReport("second", wrapped)

	fmt.Println("underlying calls:", calls)
}

根据官方语义，上面代码应表现为两次 recover 都得到 configuration is invalid，而 calls 最终为 1：

first recovered: configuration is invalid
second recovered: configuration is invalid
underlying calls: 1

这类现象在线上很容易被误判为“初始化函数不断重试并不断失败”。如果日志只记录 panic 文本，而没有记录初始化函数自己的进入计数，就会看到大量相同错误。实际上，重复的是 panic 的传播，不是资源初始化。

OnceFunc 和 Once.Do 的 panic 语义不同

sync.OnceFunc 与传统的 sync.Once.Do 都保证目标函数最多执行一次，但对 panic 的后续行为不同：

• OnceFunc：第一次执行 f 时 panic，之后每次调用返回函数都以同一个值 panic。
• Once.Do：第一次执行 f 时 panic，Once 将其视为已经返回；后续调用 Do 不再执行 f，也不会自动重放这次 panic。

package main

import (
	"fmt"
	"sync"
)

func safeCall(label string, f func()) {
	// 用局部 recover 展示每次调用是否产生 panic。
	defer func() {
		if p := recover(); p != nil {
			fmt.Printf("%s panic: %v\n", label, p)
			return
		}
		fmt.Printf("%s returned normally\n", label)
	}()
	f()
}

func main() {
	var once sync.Once
	calls := 0

	initFn := func() {
		// Do 也只会调用这个函数一次。
		calls++
		panic("init failed")
	}

	// 第一次 Do 传播 panic，第二次 Do 直接返回且不重试。
	safeCall("first", func() { once.Do(initFn) })
	safeCall("second", func() { once.Do(initFn) })

	fmt.Println("underlying calls:", calls)
}

如果初始化失败必须让所有使用者都明确失败，OnceFunc 的重复 panic 比 Once.Do 后续静默返回更一致。但这并不意味着 panic 是普通配置错误、网络错误或临时依赖故障的最佳表达方式。

并发调用时会发生什么

OnceFunc 返回的函数可以被并发调用。多个 goroutine 同时到达时，只有一个 goroutine 会执行 f，其他调用会等待这次一次性执行完成。如果 f panic，等待者继续通过同一个返回函数观察到相同的 panic 值。

因此，并发场景仍然遵循两个独立结论：

• 底层函数的副作用最多发生一次；
• 调用者可能有多个，每个调用者都可能接收到 panic。

不要在每个 goroutine 中把相同 panic 当成一次新的初始化尝试。告警聚合时，可以同时记录 panic 值、OnceFunc 包装点、首次失败时间和底层初始化进入次数，以免重复告警掩盖真实根因。

线上遇到重复 panic 怎么处理

先判断是不是 OnceFunc 重放

典型信号是：多个请求或 goroutine 报出相同 panic 值，但初始化函数中的“开始加载”“开始连接”等日志只出现一次。代码搜索又能找到该初始化函数被 sync.OnceFunc 包装。此时应把调查重点放到第一次调用，而不是把每一条后续 panic 都当作新故障。

优先保留第一次 panic 的完整堆栈

第一次调用的堆栈最有价值，因为它能到达原始的 f。后续重放不会重新进入 f，调用栈可能只显示当前包装函数调用点。日志系统应避免用后续大量相同事件覆盖或采样掉第一条堆栈。

修复依赖后不会自动恢复

OnceFunc 没有 reset 方法。即使配置文件已经修正、网络已经恢复或依赖服务重新上线，原来的包装函数仍保存失败状态，下一次调用仍会 panic。恢复路径通常是回滚错误版本、重启持有该包装函数的进程，或者在受控组件中创建一个新的 OnceFunc 实例并安全替换旧实例。

recover 只能拦截传播，不能重置状态

在请求边界或 goroutine 边界使用 recover 可以防止整个进程退出，但不会清除 OnceFunc 保存的 panic。若业务继续调用同一个包装函数，就会持续触发 recover，形成告警风暴或请求级失败循环。

需要错误返回时使用 OnceValues

可预期的初始化失败应优先用 error 表达。只需要“计算一次，并把成功或失败结果缓存给所有调用者”时，可以使用 sync.OnceValues：

package config

import "sync"

type Config struct {
	Endpoint string
}

func loadConfig() (Config, error) {
	// 这里返回可预期错误，不使用 panic 表达配置缺失。
	return Config{}, errConfigMissing
}

var loadOnce = sync.OnceValues(func() (Config, error) {
	// 结果和 error 都只计算一次，后续调用复用同一对返回值。
	return loadConfig()
})

func GetConfig() (Config, error) {
	// 调用者正常处理 error，不需要 recover。
	return loadOnce()
}

要注意，OnceValues 也不会因为返回了 error 就重新执行。第一次返回的 error 会被缓存。如果临时故障恢复后应该重试，就不能把重试需求塞进 OnceFunc、OnceValue 或 OnceValues。

需要重试时使用显式状态

重试意味着失败后状态仍允许再次尝试，成功后才进入永久完成状态。这与“无论成功还是失败都只调用一次”的 once 语义不同。可以用互斥锁保护显式状态，让失败返回 error，下一次调用再尝试：

package client

import "sync"

type Client struct{}

type LazyClient struct {
	mu    sync.Mutex
	ready bool
	value *Client
}

func connect() (*Client, error) {
	// 实际项目在这里建立连接，并把临时故障作为 error 返回。
	return nil, errDependencyUnavailable
}

func (l *LazyClient) Get() (*Client, error) {
	l.mu.Lock()
	defer l.mu.Unlock()

	// 只有成功状态才复用已经创建的客户端。
	if l.ready {
		return l.value, nil
	}

	value, err := connect()
	if err != nil {
		// 失败时不设置 ready，下一次调用仍可再次尝试。
		return nil, err
	}

	l.value = value
	l.ready = true
	return l.value, nil
}

生产代码还应补充退避、超时、熔断和指标，避免大量调用者在依赖恢复前频繁尝试。核心判断很简单：如果失败后需要再次执行，就不要用 OnceFunc 表示这段生命周期。

常见问题

recover 第一次 panic 后，再调用包装函数会正常返回吗？

不会。recover 只处理当前 panic，OnceFunc 内部仍保存失败状态；再次调用会再次 panic。

第二次 panic 会重新执行函数体吗？

不会。被包装函数最多执行一次。第二次及以后的 panic 来自保存的 panic 值。

多个 goroutine 会不会同时执行 f？

不会。OnceFunc 使用一次性同步保证 f 最多执行一次；其他调用者等待完成后，共同观察成功返回或重复 panic。

如何让修复后的配置重新加载？

原 OnceFunc 无法重置。需要重新创建包装函数并安全替换，或者重启持有状态的进程。若这是常规业务需求，应改为显式可重载状态，而不是依赖 OnceFunc。

结论

sync.OnceFunc 的 panic 语义可以概括为：f 只运行一次，panic 可以传播很多次。首次失败后，后续调用不会重试 f，而是继续以相同值 panic。排障时保留首次完整堆栈；设计时把可预期失败改成 error；确实需要失败后重试，就使用显式状态、互斥和退避机制。