UnmarshalTypeError 是 json.Unmarshal 因字段类型不匹配（如 JSON 字符串映射到 int）而抛出的 *json.UnmarshalTypeError panic，需用 errors.As 安全捕获并区分处理。
UnmarshalTypeError 是什么错误
这是 json.Unmarshal 遇到字段类型不匹配时抛出的 panic 类型，比如 JSON 里是 "123"（字符串），但结构体字段定义为 int；或者 JSON 是 {}，却想 unmarshal 到 *string。它不是普通 error，而是 *json.UnmarshalTypeError，必须用类型断言捕获。
怎么安全捕获并处理 UnmarshalTypeError
直接用 errors.As 检查 err 是否为该类型，比用 strings.Contains 或 err.Error() 解析更可靠、更语义化：
- 用
errors.As(err, &e)提取具体错误实例，e.Value是 JSON 原始值类型（如"string"），e.Type是期望的 Go 类型（如int） - 别用
if err != nil后直接 log.Fatal，会掩盖真实问题；至少区分是语法错误（json.SyntaxError）还是类型错（json.UnmarshalTypeError） - 注意：如果嵌套很深（比如 map[string]interface{} 中某字段类型错），
UnmarshalTypeError的e.Field可能为空，得靠上下文或日志补全路径
var u User
err := json.Unmarshal(data, &u)
var e *json.UnmarshalTypeError
if errors.As(err, &e) {
log.Printf("type mismatch at field %q: got %s, want %s", e.Field, e.Value, e.Type)
// 这里可 fallback、忽略、或返回自定义 error
}
常见类型错场景和对应解法
多数问题出在“JSON 字符串 vs Go 数值”或“空值处理”，而不是结构体定义本身：
- JSON 字段是
"123"，但结构体字段是int：加stringtag，如Age int `json:"age,string"`，Go 会自动尝试从字符串转数字 - JSON 字段是
null，但字段是int或string（非指针/非空接口）：改成指针（*int）或使用sql.NullInt64类型；或者用自定义UnmarshalJSON方法做容错 - 字段名大小写不一致导致没匹配上，实际值被丢进
json.RawMessage或静默忽略：开启json.Decoder.DisallowUnknownFields()提前暴露字段映射问题
为什么不用反射或通用 fallback 处理所有类型错
因为 UnmarshalTypeError 发生在解析中途，Go 已经放弃当前字段，继续执行可能让结构体处于半初始化状态：
立即学习“go语言免费学习笔记（深入）”；
- 不要在
UnmarshalJSON方法里 catch panic 并“强行赋默认值”——这会掩盖数据质量问题，下游逻辑更难 debug - 避免对整个 payload 做
map[string]interface{}中转再手动转结构体，性能差且丢失类型约束 - 真正需要灵活性的场景（如 API 接收混合类型字段），应定义明确的 union 类型（如用
json.RawMessage+ 后续分发），而不是靠错误兜底
类型错不是边缘情况，而是数据契约松动的信号。与其花精力绕过它，不如在上游校验、文档或 schema 层就卡住 —— 比如用 OpenAPI 定义字段类型，生成 Go struct 时带上严格 tag。
