Go的json.Unmarshal默认按导出字段名严格匹配JSON键，需用json tag显式映射；空值处理、嵌套结构、动态key、校验时机及Content-Type确认均为常见陷阱。
JSON字段名不匹配导致解析为空
Go 的 json.Unmarshal 默认按结构体字段的**导出名（大写开头）**匹配 JSON 键，且严格区分大小写。如果 API 返回的是 user_id，但结构体写成 UserId int 而没加 tag，字段就永远收不到值。
- 必须用
jsonstruct tag 显式声明映射关系：UserID int `json:"user_id"` - 空字符串、
null、缺失字段默认都会被忽略——除非字段类型是*int或sql.NullInt64这类可判空类型 - 嵌套对象里字段也得逐层打 tag，别指望外层 tag 能“透传”
- 如果 JSON 键名含点号（如
"data.user.name"），标准json包不支持路径式映射，得先用map[string]interface{}解一层再手动取
嵌套结构体与切片解析失败的常见写法
遇到 {"items":[{"id":1},{"id":2}]} 这类响应，容易在结构体定义上漏掉指针或搞错层级。典型错误是把切片元素类型写成值类型却忘了初始化，或嵌套结构体没导出字段。
- 切片字段必须是导出字段 + 正确 tag：
Items []Item `json:"items"`，其中Item的字段也得大写 + tag - 不要用
[]*Item除非真需要 nil 元素；多数情况[]Item更安全 - 如果某层 JSON 是动态 key（比如
{"2024-01": {...}, "2024-02": {...}}），只能先解到map[string]json.RawMessage，再对每个 value 单独json.Unmarshal - 用
json.RawMessage延迟解析能避免重复解码，但要注意它不校验格式，后续Unmarshal失败时错误位置难定位
用 validator 库做字段校验时的陷阱
直接在结构体加 validate tag（如 `validate:"required,min=1"`）很常见，但容易忽略校验时机和零值行为。
-
validate不会自动触发，必须显式调用Validate.Struct(...)，且要检查返回的error是否为nil - 数字类型字段如果 JSON 传了空字符串（
"age": ""），json.Unmarshal会设为 0，此时validate:"min=1"就会误报——得配合omitempty和指针类型（*int）才能区分“未传”和“传了 0” -
time.Time字段若 JSON 是字符串（如"2024-01-01"），标准json包无法直接解，得自定义UnmarshalJSON方法，validator 才能拿到有效值再校验 - 第三方库如
go-playground/validator对嵌套结构体默认不递归校验，需加divetag：Items []Item `json:"items" validate:"dive"`
性能敏感场景下避免反复解析
高频接口里每次请求都走一遍 json.Unmarshal + 校验，GC 和 CPU 开销明显。尤其当请求体较大或结构体嵌套深时，延迟容易突增。
立即学习“go语言免费学习笔记（深入）”；
- 别在 handler 里直接
json.NewDecoder(r.Body).Decode(&v)后立刻校验——万一校验失败，r.Body已被读完，没法重试或记录原始 payload - 先用
io.ReadAll拿到[]byte，再用json.Unmarshal；这样既能重用字节流，也方便打日志或送入审计系统 - 对固定结构的请求体，可预编译
json.Decoder实例并复用，但注意它不是并发安全的，每个 goroutine 得有自己的实例 - 如果只是校验字段是否存在、类型是否合法，用
jsoniter替代标准库能快 2–3 倍，但会增加依赖和调试复杂度
application/json 就直接解，或者前端发了 text/plain 包着 JSON 字符串——这时候 json.Unmarshal 报的错根本不像 JSON 错误，而是“invalid character 't' looking for beginning of value”。 
