mapstructure.squash能解决嵌套字段扁平化映射问题，使profile.user.name等子字段直接映射到profile.name层级，适用于配置复用、api响应不统一等场景，且仅作用于反向解码。
mapstructure.Squash 能解决哪些嵌套配置映射问题
直接用 viper.Unmarshal 解析 YAML/JSON 到结构体时，嵌套字段不会自动“提上来”——Profile.User.Name 就是 Profile.User.Name，不是 Profile.Name。只有加 mapstructure:",squash" 才能打破层级，让子结构字段出现在父结构体同一层。
常见适用场景：
-
配置文件里写的是
name: alice，但结构体定义了User User嵌入字段，想直接映射到Profile.Name - 多个配置块共用一套基础字段（如
Timeout、Retries），用嵌入 +squash复用定义，避免重复字段 - API 响应结构不统一，部分字段在
data.user下，部分在data.profile下，靠squash统一收口到顶层
注意：squash 只对 mapstructure 生效，json 包的 inline 不兼容它；也不影响序列化方向（结构体 → map），只控制反向解码（map → 结构体）。
为什么 viper.SetDefault("db.host", "localhost") 有时不生效
默认值必须在 viper.ReadInConfig() 之前设置，否则已加载的配置会“固化键状态”，后续调用 viper.Get* 时即使键不存在也不会 fallback 到默认值。
容易被忽略的细节：
- 嵌套键路径必须和
mapstructuretag 完全一致，比如结构体字段是DB Host string `mapstructure:"host"`，默认值就得设viper.SetDefault("db.host", ...)，而不是"DB.Host"或"db.Host" - 如果嵌入结构体用了
squash，默认值路径也要扁平化：例如type Server struct { TLS TLSConfig `mapstructure:",squash"` }，那TLS.Enabled对应的默认值键是"server.enabled"，不是"server.tls.enabled" -
viper.AutomaticEnv()开启后，哪怕环境变量值为空（如SERVER_PORT=），也会覆盖默认值，不会退回到SetDefault的值
YAML 扁平化为 map[string]string 的实操要点
不预定义结构体、又想避免 map[interface{}]interface{} 类型断言地狱？把 YAML 直接转成点号路径键值对是最稳的动态访问方案。
关键操作步骤：
- 用
yaml.Unmarshal先解析为map[interface{}]interface{}，再递归遍历生成扁平键 —— 路径拼接用.分隔，如database.port、features.0.name - 所有值统一转成字符串：
fmt.Sprintf("%v", val)，避免类型判断；数字、布尔、null 都变成可比较的字符串 - 遇到
nil、interface{}、chan、func等不可序列化类型，跳过或记录警告，别 panic - 路径生成时检测匿名字段：若当前字段
f.Anonymous == true且类型是struct，则不加字段名，直接递归其内部字段
这样得到的 map[string]string 可直接用于 viper.Set 注入，或配合 strings.HasPrefix 做前缀过滤，比嵌套 map 安全得多。
手动实现 MarshalJSON 扁平化时最常踩的坑
当 json:",inline" 不够用（比如嵌入字段可能为 nil，或需动态控制字段是否输出），就得重写 MarshalJSON。但直接调用 json.Marshal 原结构体会触发无限递归。
安全写法核心就两点：
- 定义类型别名绕过方法集：
type Alias MyStruct，然后构造匿名结构体嵌入*Alias，再手动补上要扁平化的字段 - 所有字段值必须显式赋值，不能依赖嵌入结构体的字段自动透出 —— 比如
Info.Age得写成Age: u.Info.Age，而不是指望u.Info自动展开 - 指针字段要判空：
if u.Info != nil { ... }，否则u.Info.Age会 panic - 字段 tag 名（如
json:"city"）必须和手动赋值的字段名一致，否则 JSON 输出字段名对不上
真正麻烦的不是写法，而是维护成本：一旦结构体字段增减，MarshalJSON 里对应的手动赋值也得同步改，漏一个就静默丢数据。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
