必须用嵌套结构体，不能写点号路径：YAML中database.host是两层嵌套，需定义Database DatabaseConfig yaml:"database"和Host string yaml:"host"，所有字段首字母大写且显式打标签，小写字段静默失效，须用gopkg.in/yaml.v3并传指针解码。
必须用嵌套结构体，不能写点号路径
YAML 中的 database.host 不是“一个键”，而是两层嵌套：顶层 key 是 database，其值是一个 map，里面再有 host。Go 的 yaml.Unmarshal 不支持类似 JSONPath 的点号路径写法，yaml:"database.host" 会被当作字面量去匹配 YAML 中一级 key 叫 database.host 的字段——这几乎总是失败。
正确做法是逐层定义导出结构体：
- 外层结构体字段名必须首字母大写，比如
Database DatabaseConfig `yaml:"database"` - 内层结构体（如
DatabaseConfig）里每个字段也必须首字母大写 + 显式yaml标签，比如Host string `yaml:"host"` - 所有嵌套层级都得手动展开，不能偷懒用
map[string]interface{}混过去（除非你后续自己做类型断言）
字段小写 = 静默失效，不是报错
yaml.Unmarshal 对非导出字段（小写开头）完全无视：不 panic、不 warn、不赋值，只留零值。你看到 Port 总是 0、Host 总是 ""，大概率是因为写了 port int 而不是 Port int。
常见错误组合：
立即学习“go语言免费学习笔记（深入）”；
-
port int `yaml:"port"`→ 字段未导出，永远为 0 -
Port int `yaml:"PORT"`→ YAML 键名大小写敏感，匹配不到port: 8080 -
Port int `yaml:"port,omitempty"`→omitempty只影响序列化（Marshal），对反向解析（Unmarshal）无作用
用 gopkg.in/yaml.v3，别碰 v2 或 v1
v2 在处理 map[string]interface{} 和空值时有 panic 风险；v1 已归档；而 gopkg.in/yaml.v3 是 Docker、Helm、client-go 等主流项目统一采用的版本，锚点、别名、严格模式、错误定位都稳定。
使用ydata-profiling（前身为pandas-profiling）生成全面的数据质量报告，包含相关性分析、缺失值模式和基数检测。导出交互式HTML仪表板和JSON摘要。
安装命令必须带 .v3：
- ✅ 正确：
go get gopkg.in/yaml.v3 - ❌ 错误：
go get gopkg.in/yaml.v2、go get gopkg.in/yaml.v3.0.0、go get github.com/go-yaml/yaml（这是 v3 的镜像，但路径不标准，可能拉错）
读取流程要检查 error，且目标必须是指针：
data, err := os.ReadFile("config.yaml")
if err != nil {
log.Fatal(err)
}
var cfg Config
err = yaml.Unmarshal(data, &cfg) // 注意 &cfg，不是 cfg
if err != nil {
log.Fatal(err)
}
动态 key 场景下慎用 map[string]any
当 YAML 里有按环境名分组的配置，比如：
staging: host: staging.example.com production: host: prod.example.com
不能直接映射成 map[string]struct{ Host string }，因为 yaml.v3 默认解到 map[string]any（不是 interface{}），你需要显式类型断言：
- 先解到
map[string]any，再对每个 value 做v.(map[any]any)或更安全的map[string]any断言 - 如果结构固定，仍推荐定义具体结构体 +
map[string]EnvConfig，避免运行时 panic -
map[string]any中的 key 类型默认是any（即interface{}），但实际通常是string，断言前最好先reflect.TypeOf(k).Kind() == reflect.String
最易被忽略的一点：嵌套结构体里的字段，哪怕外层已导出，内部字段仍需逐个大写 + 打标签——漏一个，那一层就全空。
