burntsushi/toml 是当前最稳定、广泛采用的 Go TOML 解析库，因标准库不支持 TOML；其解析快、结构体标签兼容性好、错误提示清晰，虽已归档但仍维护。
为什么用 burntsushi/toml 而不是标准库
Go 标准库不支持 TOML，必须依赖第三方。目前最稳定、被广泛采用的是 burntsushi/toml（虽已归档，但仍在维护且无严重 bug）。它解析快、结构体标签兼容性好，且错误提示相对清晰。别碰 go-toml 的 v3+（API 不兼容旧项目），除非你明确要新特性。
toml.Unmarshal 解析失败的常见原因
多数报错不是语法问题，而是结构体定义和 TOML 字段不匹配。典型现象：toml: cannot decode TOML value into *struct 或静默丢字段。
- 字段名首字母小写 → 不会被导出 →
toml无法写入/读取，必须大写 - 没加
toml:"xxx"标签，但 TOML 键名含下划线或大小写不一致（如db_port对应结构体字段DbPort，不加 tag 就会忽略） - TOML 中是数组，结构体里却定义成单个值（或反之），比如
servers = ["a", "b"]对应Servers string而非Servers []string - 嵌套表（
[[servers]]）必须对应切片，不是单个 struct；而[server]才对应单个 struct
如何安全地读取配置文件并处理缺失字段
别直接 os.ReadFile + toml.Unmarshal 后就开跑。缺字段、类型错、路径不存在都会让程序 panic 或行为异常。
- 先检查文件是否存在且可读：
os.Stat("config.toml")，避免空字节切片传给Unmarshal - 用指针接收结构体，便于检测零值字段（比如
Port int `toml:"port"`没写时默认为 0，但 0 可能是合法值，建议加omitempty或用*int） - 对必填字段，在解析后手动校验：比如
if c.Database.URL == "" { return errors.New("missing database.url") } - 避免全局变量存配置，封装成函数返回结构体，方便测试和复用
示例片段：
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
立即学习“go语言免费学习笔记（深入）”；
type Config struct {
Server struct {
Port int `toml:"port"`
} `toml:"server"`
Database struct {
URL string `toml:"url"`
} `toml:"database"`
}
data, _ := os.ReadFile("config.toml")
var cfg Config
if err := toml.Unmarshal(data, &cfg); err != nil {
log.Fatal(err) // 别忽略 err
}
嵌套数组和 inline table 的写法差异
TOML 里 [[section]] 和 [section] 完全不同，结构体定义稍有偏差就会解析为空。
-
[[servers]]→ 必须对应Servers []Server `toml:"servers"`，每个[[servers]]是一个数组元素 -
[servers.common]→ 是嵌套 inline table，结构体得写成Servers struct { Common struct{...} } `toml:"servers"` -
[servers]（单个表）→ 对应Servers Server `toml:"servers"`，不是切片 - 如果 TOML 里写了
[[servers]]但 Go 里定义成Servers Server，解析不会报错，但Servers字段始终是零值
最容易被忽略的是：TOML 数组项里允许省略重复 key（如多个 [[deploy]] 共享 region = "us"），但 Go 结构体字段不能“继承”，每个 struct 实例都得完整承载自己那一块。
