mapstructure 可在解码时自动填充 default tag 默认值，但仅对缺失字段生效；需先 yaml.Unmarshal 到 map，再 mapstructure.Decode 填默认值，最后用 validator 校验，且环境变量覆盖必须在默认值之后、校验之前完成。
用 mapstructure 解析时自动填充默认值
Go 原生 json.Unmarshal 和 yaml.Unmarshal 不会设置结构体字段的默认值，哪怕你给字段写了 struct tag。真正能“一边解码一边填默认值”的是 mapstructure 库（github.com/mitchellh/mapstructure），它在解码 map 后再映射到结构体时支持 default tag。
常见错误：直接用 yaml.Unmarshal 读配置，发现 int 字段为 0、string 为空——这不是 bug，是 Go 的零值行为，但业务上往往需要显式默认值（比如超时设为 30s）。
- 结构体字段必须导出（首字母大写），否则
mapstructure无法访问 - 使用
mapstructure.Decode替代原生解码：先yaml.Unmarshal到map[string]interface{}，再传给mapstructure.Decode -
defaulttag 只对零值生效：如果配置文件里写了timeout: 0，default:"30"不会覆盖；但若字段根本没出现，才会填默认值 - 支持嵌套结构体和 slice，默认值 tag 可逐层定义
type Config struct {
Timeout int `mapstructure:"timeout" default:"30"`
Host string `mapstructure:"host" default:"localhost"`
}
var raw map[string]interface{}
yaml.Unmarshal(data, &raw)
var cfg Config
err := mapstructure.Decode(raw, &cfg) // ← 这里填默认值
校验字段合法性用 validator + 自定义函数
仅靠默认值不够，比如 Timeout 设成 -5 就不合理，Host 不能是空字符串或非法域名。Go 生态最常用的是 go-playground/validator/v10，它支持 tag 驱动的校验，也允许注册自定义规则。
容易踩的坑：校验必须在默认值填充之后做，否则 Timeout 字段还是 0，gt=0 就会失败；且 validator 默认不校验零值字段（比如 string 为空时跳过），需显式加 required 或用 omitempty 控制。
- 先调
mapstructure.Decode填默认值，再调validate.Struct - 常用 tag：
required、min=1、max=65535、hostname、url；复杂逻辑（如“非空时必须是 IPv4”）写自定义函数 - 校验失败返回
validator.ValidationErrors，可遍历输出字段名和原因，别只打印err.Error()—— 那是单行字符串，难定位 - 注意：struct tag 中 validator 名称要和 mapstructure 字段名一致（都用
mapstructuretag 的 key），否则校验可能漏字段
type Config struct {
Timeout int `mapstructure:"timeout" default:"30" validate:"required,min=1,max=300"`
Host string `mapstructure:"host" default:"localhost" validate:"required,hostname"`
}
// ...
err := validate.Struct(cfg)
if err != nil {
for _, e := range err.(validator.ValidationErrors) {
log.Printf("config error: %s = %s", e.Field(), e.Tag())
}
}
把解析、默认值、校验打包成可复用函数
每次读配置都重复写 yaml.Unmarshal → mapstructure.Decode → validate.Struct 很冗余。建议封装一个通用函数，接受原始字节、目标结构体指针、选项（如是否严格模式）。
关键点在于错误处理顺序：必须先解码成功，再填默认值，最后校验。任一环节失败就该立即返回，避免后续操作基于脏数据。
- 函数签名类似：
func LoadConfig(data []byte, cfg interface{}, opts ...LoadOption) error - 内部用
mapstructure.DecoderConfig设置WeaklyTypedInput: true，兼容字符串转数字等常见松散类型 - 校验前检查
cfg是否为指针，否则validate.Struct会 panic - 生产环境建议加日志：记录用了哪些默认值、哪几个字段校验失败，方便排查配置问题
环境变量和配置文件合并时的优先级陷阱
很多项目用 os.Getenv 覆盖配置文件值，但顺序错了就会出问题：比如先填默认值，再用环境变量覆盖，结果环境变量是空字符串，反而把刚填的默认值冲掉了。
正确做法是“环境变量 > 配置文件 > 默认值”，即：先从配置文件解析出基础值，再用 os.Getenv 显式覆盖指定字段，最后统一校验。不要依赖 mapstructure 的 env tag，它不支持条件覆盖，且易与默认值逻辑冲突。
- 推荐手动覆盖：解析完
cfg后，按需检查os.Getenv("TIMEOUT")是否非空，再赋值 - 避免用
os.LookupEnv简单判断存在性——有些服务会把环境变量设为空字符串，这和未设置语义不同 - 覆盖后必须再次校验，因为环境变量可能引入非法值（如
TIMEOUT=abc） - 所有覆盖逻辑放在校验之前，确保最终结构体状态是干净、合法、带默认值的
