嵌套结构体字段必须导出且显式加 json:"key" 标签，因 encoding/json 仅处理首字母大写的导出字段，小写字段被跳过导致零值；api key 多为 snake_case，需显式标签映射，不可依赖字段名巧合；禁用点路径标签；空对象解 struct 得零值、解 map 得空 map；动态 key 必用 map[string]t；避免链式断言，优先用 map[string]json.rawmessage；mapstructure.squash 可扁平化嵌套配置但仅对 mapstructure.decode 生效；深层容器应抽象为语义化中间类型，提升可维护性。
嵌套结构体字段必须导出且显式加 json:"key" 标签
Go 的 encoding/json 包只处理首字母大写的导出字段，小写字段（如 user_id int）永远解析失败，值保持零值。API 返回的 key 多为 snake_case，而 Go 字段习惯 CamelCase，不加标签就完全对不上。
常见错误现象：解完结构体后字段全是零值，但没报错——因为字段未导出，json.Unmarshal 直接跳过，不 panic 也不提示。
-
json:"user_id"必须显式写，哪怕字段名碰巧是UserID↔"user_id"；否则后续重命名字段会静默失效 - 别用
json:"user.name"这类点路径标签——json包根本不支持，只会去当前层级找叫"user.name"的 key - 空 JSON 对象
{}解到 struct 得到全零值；解到map[string]interface{}得到空 map，行为不同，别混用
动态 key 场景下用 map[string]T，而非 map[string]interface{}
当 JSON 的 key 是运行时才确定的（例如 {"2024-01-01": {...}, "2024-01-02": {...}}），struct 字段无法预先定义，必须退到 map[string]T。
使用场景包括：按日期/ID/版本号索引的聚合数据、多租户配置分片、实验分组结果等微服务常见响应格式。
- 优先定义
type DailyReport struct { ... }，再声明字段为Daily map[string]DailyReport `json:"daily"` - 绝对避免
v["data"].(map[string]interface{})["items"].([]interface{})[0].(map[string]interface{})["id"]这种链式断言——极易 panic，且 IDE 无法提示、单元测试难覆盖 - 若 value 结构也不固定，用
map[string]json.RawMessage缓存原始字节，后续按需解析，避免重复解码开销
用 mapstructure.Squash 扁平化嵌套配置字段
微服务常需复用基础配置（如 Timeout、Retries），或对接多个 API 响应结构不统一（有的在 data.user，有的在 profile 层）。这时 mapstructure.Squash 能把子结构字段“提上来”。
注意：squash 只对 mapstructure.Decode（如 Viper 的 Unmarshal）生效，json.Unmarshal 不识别它；也只影响反向解码（map → struct），不影响序列化方向。
- 结构体嵌入字段加
mapstructure:",squash"标签，例如TLS TLSConfig `mapstructure:",squash"` - 对应默认值路径要扁平化：上面例子中
TLS.Enabled的默认值键是"server.enabled"，不是"server.tls.enabled" -
viper.SetDefault("db.host", "localhost")必须在viper.ReadInConfig()之前调用，否则已加载的配置会固化键状态，导致默认值失效
深层容器字段应抽象为语义化中间类型
遇到 {"result":{"payload":{"data":{"list":[{"item":{"id":1}}]}}}} 这类四层结构，别堆砌四级嵌套 struct。微服务里可读性与可维护性比“省几行代码”重要得多。
容易被忽略的细节：把 payload、data 这种纯容器字段硬塞进业务逻辑，会让结构体失去语义，后续加字段、改协议、写单元测试都变困难。
- 把无业务含义的中间层合并成一个类型，例如
type ResponseData struct { List []Item `json:"list"` } - 需要复用某子结构时，用匿名字段嵌入，而非复制字段定义
- 字段命名贴近业务：用
RouteInfo比用ChildStruct2更易维护，也方便 Swagger 文档生成
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
