应选 gopkg.in/yaml.v3：v2 对嵌套、空值、自定义类型支持弱，易 panic 或丢字段；v3 默认零值处理更安全，且需注意字段导出、标签匹配、指针初始化及锚点等高级特性。
YAML 解析库选 gopkg.in/yaml.v3 而不是 v2
Go 官方生态里最稳的 YAML 库是 gopkg.in/yaml.v3，v2 对嵌套结构、空值、自定义类型字段支持弱，容易在反射映射时 panic 或静默丢字段。比如 v2 遇到 NULL 字段会直接跳过，而 v3 默认按零值处理，更符合反射赋值预期。
实操建议：
- 用
go get gopkg.in/yaml.v3安装，别用github.com/go-yaml/yaml（那是 v3 的镜像，但 import 路径不统一易混淆） - 解析前先用
yaml.Unmarshal把字节流转成map[String]interface{}粗校验一次，能提前暴露语法错误，避免反射阶段才崩 - 如果配置含时间字段（如
expires: 2025-04-01T00:00:00Z），v3 默认不识别 RFC3339，得手动注册yaml.Node解析器或改用time.Time类型 +UnmarshalYAML方法
反射赋值前必须检查结构体字段是否可导出
Go 反射无法写入非导出字段（首字母小写），哪怕 YAML 键名完全匹配，字段也会被跳过且无提示。这是最常踩的坑——配置明明写了，运行时却是零值。
实操建议：
- 所有待映射的结构体字段必须大写开头，例如
Port int `yaml:"port"`，不能写port int - 用
reflect.StructField.IsExported()在加载器里加一层校验：遍历字段时发现不可导出，立刻panic或 log.Warn 并退出，别等上线后查半天 - 如果真要支持私有字段（极少见），得用
unsafe强制写入，但会破坏内存安全，不推荐
yaml 标签里的 key 必须和 YAML 文件中实际 key 完全一致（包括大小写和下划线）
YAML 是大小写敏感的，yaml:"db_host" 和 db-host 或 DB_HOST 都不匹配。反射靠标签做键名映射，错一个字符就断连。
实操建议：
- 统一约定配置文件用
snake_case，结构体字段用CamelCase，标签显式声明，例如：DBHost string `yaml:"db_host"` - 避免依赖默认命名规则（比如自动把
DBHost转成dbhost），v3 不支持这种 magic，得自己写func (t *T) UnmarshalYAML才能干预 - 测试时用一段带注释的 YAML 示例跑一遍，打印出反序列化后的结构体，肉眼核对字段值，比单测更容易发现拼写偏差
嵌套结构体 + 指针字段容易导致 nil panic
当 YAML 中某嵌套对象缺失（比如没写 redis: 块），而结构体里对应字段是 *RedisConfig，反射不会自动 new 出指针目标，后续访问 cfg.Redis.Timeout 就 panic。
实操建议：
- 优先用值类型嵌套（
Redis RedisConfig），除非明确需要区分“未配置”和“配置为空” - 如果必须用指针，在反射赋值后加一层初始化逻辑：遍历所有指针字段，若为
nil且 YAML 数据里对应 key 存在（通过map[string]Interface{}初步解析结果判断），则field.Set(reflect.New(field.Type.Elem())) - 别依赖
omitempty标签来规避——它只影响序列化输出，对反序列化无作用
复杂点在于，YAML 支持锚点（&common）、引用（*common）和混合类型（同一字段有时是字符串有时是对象），这些没法靠纯反射兜住，得在 UnmarshalYAML 方法里手动处理。多数项目其实用不到，但一旦用了，就得放弃通用加载器，退回到具体类型定制。