Go sync.OnceFunc 没有执行状态时怎样设计可观测标记

sync.OnceFunc 返回的是一个可并发调用、但只执行一次的函数，它没有提供“是否执行过”或“当前是否初始化成功”的查询方法。需要可观测性时，正确做法是增加一个独立的原子状态；不要读取内部实现，也不要让这个状态变量反过来充当一次性执行闸门。

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

先区分“执行过”和“初始化成功”

很多代码把 done 当作“回调进入过”的标记，但读者真正想知道的可能是配置已经可用、连接已经建立，或者初始化是否发生过 panic。三者不是同一个事实。OnceFunc 的回调成功返回后，才能把“已完成”解释为“初始化成功”；如果回调中途 panic，成功标记不应被误写。

用原子状态搭配 OnceFunc 建立观测面

最小方案可以只使用 atomic.Bool：回调正常结束时写入 true，查询函数用 Load 读取。若还要区分“尚未开始”和“正在执行”，则使用 atomic.Uint32 保存枚举状态。这个变量只提供可见性，不参与决定哪个 goroutine 可以进入回调。

为成功、运行中和 panic 设计更新时机

把状态写入点放在回调内部，并明确每个值的语义。进入回调后先写 running；正常返回路径写 succeeded；如果要观测 panic，则用 defer 捕获、写入 failed，再把 panic 原样抛回去。这样既不改变 OnceFunc 的重复 panic 语义，也不会把失败误报为成功。

一段可复用的四态实现

下面的示例把状态查询和一次性执行分开。State 可以被健康检查或调试接口读取，但它不能替代 initOnce。如果初始化回调 panic，failed 会先发布，随后重新抛出同一个值，后续调用仍由 OnceFunc 处理。

package main

import (
    "fmt"
    "sync"
    "sync/atomic"
)

const (
    stateIdle uint32 = iota
    stateRunning
    stateSucceeded
    stateFailed
)

var initState atomic.Uint32

var initOnce = sync.OnceFunc(func() {
    // 这个值只描述回调已经进入，不负责抢占执行权。
    initState.Store(stateRunning)
    defer func() {
        if recovered := recover(); recovered != nil {
            // 失败状态先对外可见，再保持 OnceFunc 的 panic 语义。
            initState.Store(stateFailed)
            panic(recovered)
        }
    }()

    // 这里放一次性准备逻辑，例如加载只读配置或建立共享资源。
    prepareSharedResource()
    // 只有正常返回，才能把状态解释为初始化成功。
    initState.Store(stateSucceeded)
})

func prepareSharedResource() {
    // 示例函数代表真实初始化，不把输出伪装成运行结果。
}

func State() uint32 {
    // 原子读取避免健康检查与初始化写入产生数据竞争。
    return initState.Load()
}

func main() {
    // 调用方仍然调用 OnceFunc，而不是先读状态再自行决定是否初始化。
    initOnce()
    fmt.Println(State() == stateSucceeded)
}

示例中的 Store 与 Load 只解决状态发布和读取的并发安全。它们没有把 State() == stateIdle 与 initOnce() 组合成“检查后执行”的逻辑；否则多个调用方会重新实现一套竞态控制，反而削弱 OnceFunc 的职责边界。

并发检查清单与常见边界

• 健康检查只读取状态，不在读取结果后直接决定是否执行初始化。
• 初始化需要可重试时，不要偷偷复用同一个 OnceFunc；应重新设计生命周期对象。
• 只需要成功标志时，优先用两态布尔值，避免把“失败”写成普通完成。
• 状态接口应说明读取时可能看到 running，这不等同于已卡死。

sync.OnceFunc 能直接查询是否执行过吗？

不能。它返回一个函数，不暴露内部完成位。需要查询时由调用方维护独立状态，并保证该状态不参与执行竞争。

为什么不在回调开始时就写 succeeded？

因为开始执行不等于准备完成。回调之后可能返回错误、panic 或尚未发布完整资源；成功状态应放在正常返回路径。

failed 状态会让 OnceFunc 自动重试吗？

不会。状态变量只是观测面；OnceFunc 仍保持一次性语义。发生 panic 后再次调用的行为应以官方文档定义为准，不要把状态标记当作重试开关。

事实依据：sync.OnceFunc 官方文档、Go 官方 sync.Once 源码。本文的状态枚举和资源准备场景是原创示例。