Go 的 json.Unmarshal 不会 panic，非法 JSON 返回 json.SyntaxError（含 Offset 定位），类型错误实为 json.UnmarshalTypeError；需用 errors.As 捕获，避免字符串匹配，注意嵌套字段错误路径缺失、重复解析性能问题及部分解析导致的隐蔽错误。
JSON 解析时 panic 了，其实是 SyntaxError
Go 的 json.Unmarshal 不会 panic，但一旦输入是非法 JSON（比如多了一个逗号、少了个引号、用了单引号），它会返回 *json.SyntaxError。这个错误类型有 Offset 字段，能准确定位到出错的字节位置，比笼统的 “invalid character” 有用得多。
常见错误现象：json: cannot unmarshal string into Go struct field X of type int 看似是类型问题，但根源可能是前面某处语法错导致解析器提前退出、后续字段错位——所以得先排除 SyntaxError。
- 检查错误是否为
*json.SyntaxError：用errors.As(err, &se)断言，别只看err.Error() -
se.Offset是从 0 开始的字节偏移，配合原始 JSON 字符串切片可快速定位，例如fmt.Printf("at offset %d: %q", se.Offset, string([]byte(jsonStr)[se.Offset-10:se.Offset+10])) - 注意：如果 JSON 来自 HTTP body 或文件流，
Offset是相对于当前已读部分的，不是整个响应体
TypeError 其实是字段类型不匹配，不是 JSON 标准里的 TypeError
Go 的 json 包里没有叫 TypeError 的公开错误类型。你看到的 json: cannot unmarshal ... into Go value of type ... 是 *json.UnmarshalTypeError，它包含 Value（JSON 中的实际值，如 "string"）、Type（期望的 Go 类型）、Struct 和 Field（如果在结构体里）。
这错误常出现在接口松散、前后端约定模糊的场景，比如后端返回 "count": 123，但前端文档写的是字符串，SDK 却定义成 Count string。
立即学习“go语言免费学习笔记（深入）”；
- 用
errors.As(err, &te)捕获*json.UnmarshalTypeError，比字符串匹配更可靠 -
te.Value是原始 JSON token 的描述（如"number"、"string"、"null"），不是具体值；想看真实内容得自己解析那段 JSON 片段 - 如果字段可能有多种类型（比如 number 或 string），别硬转，改用
interface{}或自定义UnmarshalJSON方法
嵌套结构体里字段解析失败，错误位置容易误判
当 JSON 解析失败发生在嵌套结构体内，UnmarshalTypeError.Field 只返回最内层字段名，不会带路径。比如 Root.Data.Items[0].Name 解析失败，te.Field 可能只是 "Name"，看不出上下文。
这会让排查变慢，尤其在 API 返回几十个字段、结构体嵌套三四层时。
- 建议在关键结构体上实现
UnmarshalJSON，把外层字段名拼进错误信息，例如：return fmt.Errorf("parsing %s.%s: %w", "User.Profile", te.Field, err) - 或者统一包装一层解析函数，记录当前解析路径（用
json.Decoder的More()和手动跳过字段可辅助构建路径，但成本高，一般只在调试期加） - 避免深度嵌套结构体直接传给
json.Unmarshal，中间加一层扁平化或分段解析
性能与兼容性：别在循环里反复解析同一份 JSON 字符串
每次调用 json.Unmarshal 都会重新 tokenize 和验证语法。如果你在 for 循环中对同一段 JSON 做多次解析（比如为了取不同字段），不仅慢，还可能掩盖真正的错误源——因为第一次解析失败后，后续调用仍会报错，但 offset 位置可能因缓冲或复用而漂移。
- 一次解析，多次读取：用
json.RawMessage延迟解析子字段，或解析到map[string]interface{}后按需转换 - 如果必须多次解析，确保每次传入的是独立的
[]byte切片（避免底层共用底层数组导致意外修改） - 注意 Go 1.20+ 对超长数字字符串（如 1000 位整数）默认拒绝解析，会返回
SyntaxError，这不是 bug，是安全限制；如需支持，得用UseNumber()配合手动转json.Number
最难 debug 的永远不是报什么错，而是错误发生时你根本没意识到 JSON 已被部分解析成功——比如前 9 个字段 ok，第 10 个字段语法错，但结构体前 9 个字段已经被赋值，后续逻辑基于“半成品”继续跑，结果错得更隐蔽。
