Go init 函数执行顺序为什么和文件名不应绑定

项目拆分文件后，最容易出现一种“看起来顺序很明确”的代码：把默认值放进 z_defaults.go，把配置读取放进 a_config.go，然后默认它们会按文件名参与初始化。这个假设不稳。Go 真正关心的是包级变量之间能否从代码引用关系推导出依赖；如果没有依赖，多个文件的声明顺序取决于构建系统把文件交给编译器的顺序，文件名不是业务协议。

要修复 init 顺序问题，先把数据依赖写进初始化表达式或函数体，再把有副作用的注册动作收拢到一个可调用、可测试的初始化入口。不要用文件名前缀编排运行时顺序。

先分清依赖顺序和文件呈现顺序

Go 包初始化大致分成两层：先为包级变量计算初值，再调用这个包里的 init 函数。包级变量的初始化会反复选择“已经就绪且在声明顺序中最靠前”的变量，因此只要存在真实依赖，顺序就不会靠猜。

例如下面的两个文件名很容易让人误判。config 通过 readConfig 的函数体引用了 defaultPort，这是一条代码层面的依赖；即使以后调整文件名，也不应该改变这条依赖关系。

// a_config.go
package app

// config 依赖 readConfig，readConfig 又读取 defaultPort。
var config = readConfig()

// Config 表示包启动时需要的最小配置。
type Config struct {
	Port int
}

// readConfig 的函数体引用 defaultPort，形成可分析的传递依赖。
func readConfig() Config {
	return Config{Port: defaultPort}
}

// z_defaults.go
package app

// defaultPort 是 readConfig 的默认输入，而不是靠文件名排在前面。
var defaultPort = 8080

相反，如果两个变量互不引用，或者依赖藏在编译器无法从词法引用中识别的外部状态里，跨文件的先后就不能当作稳定契约。把文件改名、加入平台文件、切换 build tag，都可能改变构建输入。工程上可以让文件名保持字典序以获得可复现的构建行为，但这不等于业务代码可以把 a_、z_ 当成生命周期控制器。

查看实际参与构建的文件集合

排查“换个文件名就变了”的问题时，先确认编译器实际看到了哪些文件。平台后缀、build tag、生成文件和测试文件会让“目录里看到的文件”与“当前构建输入”不一样。

# 查看当前构建条件下各包的文件集合和构建元数据
go list -json ./...

# 只检查某个包时，把 ./... 换成具体导入路径
go list -json ./internal/app

重点看 GoFiles、CompiledGoFiles、IgnoredGoFiles 以及项目使用的构建条件。这个命令适合确认输入集合，不适合证明“某个文件名就是初始化顺序”。如果问题只在特定平台出现，还要用对应的 GOOS、GOARCH 或 -tags 重复查看。

让包级变量依赖写在代码里

初始化依赖分析不仅看变量右侧的一眼引用，也会沿着当前包内函数和非接口方法的引用继续追踪。因此，把默认值作为函数参数或明确的包级引用，比在注册函数里偷偷读取全局状态更可靠。

package app

// Config 是启动配置，字段值来自显式的默认输入。
type Config struct {
	Port int
}

// defaultPort 是 readConfig 的明确依赖。
var defaultPort = 8080

// config 的初值依赖 readConfig，编译器可以继续分析函数体。
var config = readConfig()

// readConfig 只组装数据，不在初始化阶段启动 goroutine 或写外部状态。
func readConfig() Config {
	return Config{Port: defaultPort}
}

这里的重点不是把所有全局变量都消灭，而是让“谁需要谁”能从代码中读出来。尤其要小心接口回调、注册表、环境读取和文件写入：它们可能形成运行时的数据联系，却没有形成规范意义上的词法依赖。初始化阶段最好只做纯数据准备；需要校验、返回错误或访问外部资源的动作，放到显式函数里。

把 init 中的隐式顺序改成显式编排

同一个文件里的多个 init 会按源代码出现顺序执行；多个文件里的 init 则按文件呈现给编译器的顺序执行。更重要的是，包级变量全部初始化后，Go 才开始调用这些 init，而且初始化过程在单个 goroutine 中顺序进行。这个机制适合轻量、无须被调用方控制的包准备，不适合承载一条跨文件的业务启动流程。

如果确实需要注册指标和路由，至少先把同一条顺序放在一个函数体内；更稳妥的方式是提供返回错误的 Setup，让程序入口决定什么时候调用。

package app

// Registry 保存启动阶段创建的注册结果。
type Registry struct{}

var registry *Registry
var config Config

// Setup 把初始化动作收拢到显式入口，调用方可以处理失败。
func Setup(cfg Config) error {
	next := &Registry{}
	// 先准备共享注册表，再把同一个对象交给各注册函数。
	if err := registerMetrics(next); err != nil {
		return err
	}
	if err := registerRoutes(next, cfg); err != nil {
		return err
	}
	registry = next
	config = cfg
	return nil
}

// init 只保留兼容性很强的轻量准备，不再编排业务注册顺序。
func init() {
	// 这里不要偷偷调用多个跨文件注册函数。
}

对于确实必须使用 init 的包，可以把相关函数和依赖放在同一文件，并让每次动作幂等；但调用方仍然无法像调用 Setup 那样检查错误、选择时机或在测试中注入配置。显式入口的价值不在于“更快”，而在于顺序、输入和失败点都出现在调用点附近。

用变更文件和构建条件做反向检查

修好后不要只在当前目录运行一次就结束。最小的反向检查是重命名承载默认值的文件、切换一个实际使用的 build tag，并确认初始化结果仍由变量依赖或 Setup 调用关系决定，而不是由前缀字母决定。

• 包级变量：每个非平凡初值都能指出它依赖的变量、函数或配置输入。
• init：只保留无错误返回需求、无外部副作用或必须自动注册的轻量动作。
• 显式入口：初始化失败能返回错误，测试能传入不同配置，注册函数不会偷偷读取未准备好的全局状态。
• 构建条件：至少检查默认平台与项目实际发布平台的 go list -json 文件集合。

一句话判断标准是：删除文件名里的排序暗示后，程序仍能从依赖和调用关系推导出初始化行为。如果不能，就说明顺序还没有真正写进代码。

常见问题

Go 会保证同包文件按文件名排序吗？

语言规范把多文件声明顺序定义为文件被呈现给编译器的顺序，并鼓励构建系统使用字典序来获得可复现行为；这不是让业务代码依赖文件名的语言级保证。

变量初始化一定按源代码从上到下吗？

不是。可分析的初始化依赖会先于普通声明顺序；没有依赖时才会落到文件呈现后的声明顺序。函数体里引用的当前包变量也可能形成传递依赖。

什么时候还可以使用 init？

例如注册不可变的编解码器、校验包内常量或完成必须自动发生的轻量准备。只要动作需要配置、返回错误、访问外部资源或依赖多个跨文件副作用，就更适合改成显式初始化函数。