结构体字段必须首字母大写且带匹配的yaml:"key"标签，否则yaml.Unmarshal静默设零值；需用os.ReadFile读取并传结构体指针，动态键名应实现UnmarshalYAML接口，业务逻辑如默认值须后置处理。
结构体字段没导出或标签不匹配，yaml.Unmarshal 就会静默设零值，不是 bug，是 Go 反射机制的必然行为。
结构体字段必须首字母大写 + 显式 yaml:"key" 标签
YAML 键名（如 redis_url）和 Go 字段名（如 RedisUrl）默认不自动转换。不加 yaml:"redis_url" 标签，解析器会去找 redisurl（全小写无下划线），而不是你 YAML 里写的那个键。
- 小写字段（如
port int）会被yaml.Unmarshal完全忽略，不报错、不警告，值永远是0 - 嵌套结构体里的字段也必须导出，不能只导出顶层结构体
-
yaml:"port"中的字符串必须和 YAML 文件里实际 key 完全一致（包括大小写、下划线、连字符） - 如果 YAML 里是
skip-header-validation: true，标签就得写成yaml:"skip-header-validation"，不能写成yaml:"skip_header_validation"
读文件必须用 os.ReadFile，且传指针给 yaml.Unmarshal
ioutil.ReadFile 已在 Go 1.16+ 彻底弃用；继续用会触发编译警告，且底层逻辑已过时。更关键的是：哪怕读取成功，若把结构体变量本身（而非指针）传给 yaml.Unmarshal，它根本无法修改原值。
- ✅ 正确：
data, err := os.ReadFile("config.yaml")；err != nil必须检查，否则后续 panic 是大概率事件 - ✅ 解析必须传指针：
yaml.Unmarshal(data, &cfg)，不是yaml.Unmarshal(data, cfg) - 文件路径不确定时，先用
os.Stat("config.yaml")检查是否存在，避免运行时报no such file or directory - 读完可简单检查前几个字节是否含 BOM 或不可见控制符：
bytes.HasPrefix(data, []byte{0xEF, 0xBB, 0xBF})
动态键名（如 V1、staging）不能硬套结构体
当 YAML 顶层是运行期才确定的键（比如不同环境、不同 API 版本），定义固定结构体字段会失败。直接用 map[string]interface{} 虽能读，但后续类型断言极易 panic —— 尤其 v3 默认解析出的是 map[string]any，不是 map[string]interface{}，更不是旧版 v2 的 map[interface{}]interface{}（后者在 v3 中会直接 panic）。
立即学习“go语言免费学习笔记（深入）”；
- 安全做法：定义一个结构体，实现
yaml.Unmarshaler接口，在UnmarshalYAML方法中先提取已知字段，再把剩余部分解析为map[string]MajorVersion - 临时调试可用
yaml.Node，手动遍历树结构，但别上生产 - 避免写类似
v["V1"].(map[string]interface{})这种代码——v3 下大概率 panic，且类型不安全 - 如果只是部分字段动态（比如
extras），顶层仍用结构体，仅该字段声明为map[string]interface{} `yaml:"extras"`
默认值、环境适配等业务逻辑必须后置处理
yaml.Unmarshal 的唯一职责是“准确还原 YAML 字节到 Go 值”。任何默认值填充、环境变量覆盖、字段联动校验，都应在 Unmarshal 成功之后、配置真正被使用之前统一做。
- 不要在
UnmarshalYAML方法里写if e.Port == 0 { e.Port = 8080 }—— 违反单一职责，且测试困难 - 敏感字段（如密码）建议用
*string类型，配合omitemptytag，避免零值覆盖意图 - YAML 中的
null值会让对应字段保持零值，不会 panic，但可能引发后续空指针 —— 关键字段需显式存在性校验 - 混合加载
.env和 YAML 时，顺序和覆盖规则必须自己编码，没有库能自动合并；注意命名差异（DB_HOSTvsdb_host）
最易被忽略的点：结构体字段导出是反射生效的前提，而 yaml: 标签是映射正确的保障——这两者缺一不可。少写一个大写字母，或漏掉一个引号里的字符串，Unmarshal 就只是安静地给你一个全零结构体。
