Go 包初始化顺序与全局变量依赖排查

在 Go 服务里遇到“配置明明写了，启动时却读到默认值”时，先不要把锅甩给 init()。更稳妥的排查顺序是：先看导入图，再看包级变量的依赖表达式，最后看 init 函数是否把隐藏动作塞进了启动阶段。Go 会先初始化被导入的包，每个包只初始化一次；包内变量则按“已经满足依赖且在声明顺序中最靠前”的规则求值，变量初始化完成后才调用该包的 init。

这意味着“文件名看起来靠前”“某个 init 写在文件顶部”都不是可靠依据。下面用一个配置注册场景，把三个边界拆开。

先从导入图判断包级初始化边界

假设 main 导入 app，app 又导入 config 和 log。启动时不是直接从 main() 开始，而是先让依赖包完成自己的包级变量初始化和 init，然后才轮到依赖它们的包。

因此，看到 config 的全局对象在 app 使用前已经有值，只能说明导入关系成立，不能说明它读取的是正确配置。真正决定值的，是 config 包内部变量之间的依赖以及它们读取配置的时机。

再按依赖关系排查包级变量

包级变量不是简单地“从上到下执行”。编译器会分析初始化表达式中的引用；某个变量依赖的函数体又引用了另一个变量时，这种依赖还会传递。一个便于排查的缩小示例是：

package config

import (
	"net/http"
	"os"
	"time"
)

var endpoint = readEnv("SERVICE_ENDPOINT") // 先得到服务地址
var timeout = 3 * time.Second               // 明确写出的默认超时
var client = &http.Client{Timeout: timeout}  // client 依赖 timeout

func readEnv(key string) string {
	// 读取逻辑应保持纯粹，避免在包变量求值时再触发注册动作。
	return os.Getenv(key)
}

这个例子里，client 会依赖 timeout，但不会因为它在代码中排得更靠后就自动解释 endpoint。排查时把表达式先拆成节点，再问三个问题：它引用了哪个包级变量？引用是否藏在函数体或方法体里？这些变量是否跨文件声明？

尤其要警惕“看起来没有依赖”的函数调用。初始化表达式调用函数时，函数体里对同包变量的引用也会进入依赖分析；但接口方法带来的隐藏数据依赖不应被当成稳定的排序依据。能显式传参，就不要把关键配置藏在全局读取里。

把 init 留给明确的注册和校验

一个包可以有多个 init 函数。包级变量全部赋值后，才会按源文件呈现给编译器的顺序调用它们；同一个包的初始化过程在单个 goroutine 中串行推进，前一个 init 未返回时不会调用下一个。

package config

var registry = map[string]string{} // 只创建容器，不读取外部状态

func register(key, value string) error {
	// 固定注册逻辑保持可重复，外部配置交给显式加载函数处理。
	registry[key] = value
	return nil
}

func init() {
	// 注册固定的默认值；失败时直接终止启动，避免服务带错配置运行。
	if err := register("default", "local"); err != nil {
		panic(err)
	}
}

init 适合做不可缺少的静态注册、表驱动初始化和启动前校验；不适合悄悄读取网络、依赖环境顺序，或启动后台 goroutine 代替显式生命周期管理。需要外部输入的配置，建议改为 Load 或构造函数，让调用方看见依赖并能在测试中替换。

发布前的初始化排查清单

• 先画导入图，确认目标包是否在使用者之前完成初始化，避免把导入顺序和文件顺序混在一起。
• 把包级变量按“表达式引用—传递依赖—声明顺序”列出来，重点看函数体、方法体和跨文件声明。
• 把外部配置读取从全局变量中移到显式加载函数，必要时记录输入是否为空，但不要在初始化阶段打印敏感值。
• 检查每个 init 是否有清楚的失败策略；能由构造函数表达的动作，不要继续堆进 init。

常见疑问是：能否靠调整文件名控制初始化？不应把它当作业务契约；多文件声明顺序取决于文件呈现给编译器的顺序，构建系统通常会按词法顺序提供文件，但更好的做法是消除对顺序的依赖。另一个问题是多个包是否会重复执行 init：不会，同一个包在一次程序初始化中只初始化一次。

把导入图、变量依赖和 init 分成三层看，启动时序问题就从“猜哪个文件先跑”变成了可解释的依赖排查。