mapstructure解码需确保字段导出（首字母大写）、类型严格匹配、传入可寻址指针，否则静默失败；tag仅控制键名映射，不解决反射可见性问题。
Go 读配置文件时想把 YAML/JSON 中的 map 结构自动转成 struct 字段，核心就一条：别用原生 json.Unmarshal 或 yaml.Unmarshal 直接塞 struct，得靠 mapstructure —— 但它的默认行为极容易静默失败，不报错也不赋值。
字段必须导出（首字母大写）才能被 mapstructure 写入
这是最常踩的坑。哪怕你加了 json:"user_id" 或 mapstructure:"user_id" tag，只要字段是小写（比如 id int），mapstructure.Decode 就直接跳过，不 panic、不 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根本不会尝试写它
嵌套结构和切片类型必须严格匹配
源数据是 map[string]interface{}，但 struct 字段类型稍有偏差，就会丢数据、panic 或静默失败。
- 源数据
"scores": []interface{}{95.5, 87.0}→ struct 字段必须是Scores []float64，不能是[]interface{}（后续取值会 panic） - 源数据
"profile": map[string]interface{}{"city": "Beijing"}→ 字段得是Profile ProfileStruct或*ProfileStruct，不能是map[string]interface{} - 源数据
"tags": []interface{}{"go", "web"}→ 字段必须是Tags []string，不是[]interface{} -
Metadata map[string]string要求源数据 value 全是 string 类型，如果混了 int，转换会失败（除非开WeaklyTypedInput: true，但不推荐）
必须传可寻址指针，否则 decode 失败
mapstructure.Decode 必须写入目标 struct 的内存地址，传值或双重指针都会出问题。
- 错：
var u User; mapstructure.Decode(m, u)→ 报cannot decode into nil struct（其实是不可寻址） - 对：
var u User; mapstructure.Decode(m, &u) - 如果 u 已是
*User（比如u := &User{}），就直接传u，别写&u，否则变成**User - 初始化建议用
u := User{}或var u User，再传&u；避免用var u *User（此时 u 是 nil，decode 会 panic）
多余字段默认静默忽略，需显式开启校验
配置文件里多了一个字段（比如 "debug_mode": true），但 struct 没定义对应字段？mapstructure 默认什么也不做——上线后某个开关没生效，你得翻半天日志才意识到是字段名拼错了。
- 启用字段校验：
mapstructure.Decode(&mapstructure.DecoderConfig{ ErrorUnused: true, Result: &u, Raw: m }) - 想支持字符串转数字等宽松转换，加
WeaklyTypedInput: true，但要小心掩盖格式错误（比如"123abc"转 int 可能截断） -
*string字段遇到 nil 值不会自动 new 出指针，得配DecodeHook处理，否则字段保持 nil
真正麻烦的从来不是“怎么解析”，而是“为什么没解析”——mapstructure 的静默策略让它像一个不说话的同事，出问题只留结果，不给线索。检查导出性、类型一致性、指针传递、未使用字段这四点，基本覆盖 90% 的绑定失败场景。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
