mapstructure.decode要求字段必须导出（首字母大写），否则静默跳过赋值；必须传可寻址指针，类型须严格匹配；tag仅控制键名映射，不解决反射可见性问题。
字段必须导出，否则静默失败
mapstructure 依赖反射写入字段，而 Go 反射只能访问首字母大写的导出字段。小写字段（如 id int）哪怕加了 json:"user_id" 或 mapstructure:"user_id" tag，也完全不会被赋值——不报错、不 warn、值永远是零值。
- 错误写法：
type User struct { id int `json:"user_id"` }→ 解析后id永远为0 - 正确写法：
type User struct { ID int `json:"user_id"` }或Id int `json:"user_id"` } - tag 的作用只是映射键名，它不能绕过导出规则；
mapstructure:"user_id"和json:"user_id"效果等价，但前提是字段本身可被反射访问
必须传结构体指针，不能传值
mapstructure.Decode 需要可寻址的目标地址才能写入字段。传值（如 mapstructure.Decode(m, u)）会导致不可寻址错误，常见报错是 cannot decode into nil struct——这其实不是 struct 为 nil，而是你没传指针。
- 推荐初始化方式：
var u User，然后传&u - 若已声明为指针：
u := &User{}，直接传u，别写&u（否则变成**User，panic） - 避免
var u *User（此时u == nil），decode 会 panic
嵌套结构和切片类型必须严格匹配
mapstructure 不做运行时类型推断。源数据是 map[string]interface{} 或 []interface{}，目标 struct 字段类型稍有偏差，就会丢数据、panic 或静默跳过。
- 源数据
"profile": map[string]interface{}{"city": "Beijing"}→ 字段必须是Profile ProfileStruct或*ProfileStruct，不能是map[string]interface{} - 源数据
"scores": []interface{}{95.5, 87.0}→ 字段必须是Scores []float64，写成[]interface{}后续取值会 panic - 源数据
"tags": []interface{}{"go", "web"}→ 字段必须是Tags []string，不是[]interface{} - Metadata 类型如
map[string]string要求所有 value 都是 string；混入 int 会失败，除非显式开启WeaklyTypedInput: true（不推荐）
多余字段默认忽略，需主动校验
配置文件里多一个 "debug_mode": true，但 struct 没定义对应字段？mapstructure 默认什么都不做。上线后开关失效，你得翻日志、比对 schema 才能发现是拼写错误。
- 启用字段校验：用
mapstructure.DecodeMetadata获取Unused字段列表 - 或在
DecoderConfig中设ErrorUnused: true，遇到未定义 key 直接返回 error - 想保留未映射字段？加一个
Other map[string]interface{} `mapstructure:",remain"`字段
WeaklyTypedInput: true，或者字段名大小写+下划线映射没对齐——这两个点最容易被当成“bug”反复折腾。golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
