JSON是现代Web开发中最常用的数据交换格式，Golang标准库提供的encoding/json包让序列化和反序列化变得非常方便。但方便的背后也隐藏着不少坑：一个字段类型不匹配就可能让整个解析失败，而返回的错误信息又常常语焉不详，比如只告诉你cannot unmarshal string into Go value of type int，却不告诉你是JSON里哪个字段出了问题。这篇文章就来系统地梳理Golang中JSON解析错误的产生原因和处理办法，帮助你快速定位问题并写出更健壮的解析代码。
常见的JSON解析错误有哪些
要正确处理错误，先得知道错误从哪来。使用json.Unmarshal解析失败时，最常见的一类错误是类型不匹配。比如JSON中某个字段是字符串"age": "25"，而你的结构体定义的是Age int，Unmarshal就会直接报错并中止整个解析过程。这一点和很多动态语言不同，Go的解析是严格的，不会帮你做隐式转换。
第二类常见错误是字段名匹配问题。Go默认按照字段名大小写不敏感的方式匹配JSON键，所以user_name和UserName能对上，但如果结构体字段是私有的（小写开头），Unmarshal会静默跳过，不报错也不赋值。这种“不报错的错误”往往更难排查，很多初学者发现解析完字段全是零值，就是因为这个原因。
第三类是数字精度问题。JSON里的数字如果没有小数点，Go会默认解析成float64，如果你用map[string]interface{}去接一个大整数，比如订单号1234567890123456789，就会发现精度丢了，末尾几位变成了0。这种情况在处理第三方接口返回的ID时特别常见，务必引起注意。
json.Unmarshal和json.Decoder该怎么选
处理JSON数据有两种主流方式。第一种是先把数据读成[]byte再调用json.Unmarshal，适合数据量不大、一次性拿全的场景。第二种是使用json.NewDecoder从io.Reader流式读取，适合HTTP请求体、大文件这种边读边解析的场景。
// 方式一：Unmarshal一次性解析
data := []byte(`{"name":"tom","age":25}`)
var u User
if err := json.Unmarshal(data, &u); err != nil {
log.Fatalf("解析失败: %v", err)
}
// 方式二：Decoder流式解析
decoder := json.NewDecoder(resp.Body)
var u User
if err := decoder.Decode(&u); err != nil {
log.Fatalf("解析失败: %v", err)
}
两者在错误处理上有个关键区别：Unmarshal在遇到类型不匹配时会继续解析剩余字段，最后返回第一个遇到的错误；而Decoder默认遇到格式错误的JSON会立即停止。另外Decoder可以用decoder.DisallowUnknownFields()来拒绝未知字段，这在需要严格校验JSON结构的场景下很有用，比如客户端和服务端版本不一致时能及早发现字段变更。
对于大文件解析，推荐用Decoder配合流式读取，避免把几百MB的数据一次性加载进内存。如果JSON是一个数组，可以先解码成json.RawMessage的切片再逐条处理，内存占用能降低一个数量级。
如何精准定位出错的字段
标准库返回的错误信息不够友好，定位问题最直接的手段是自定义类型和利用json.UnmarshalTypeError。这个结构体里包含了Field、Type、Value等字段，可以直接判断错误发生在哪个字段上：
var u User
err := json.Unmarshal(data, &u)
if err != nil {
var typeErr *json.UnmarshalTypeError
if errors.As(err, &typeErr) {
fmt.Printf("字段 %s 类型错误，JSON值是 %s，期望类型 %s\n",
typeErr.Field, typeErr.Value, typeErr.Type)
return
}
// 其他错误，比如JSON语法本身不合法
var synErr *json.SyntaxError
if errors.As(err, &synErr) {
fmt.Printf("JSON语法错误，出错位置在第 %d 个字符附近\n", synErr.Offset)
}
}
另一个实用技巧是先用json.Valid快速校验JSON合法性，再决定是否进行完整解析。在调试阶段，也可以把数据先解析到map[string]interface{}里打印出来，肉眼确认结构后再写对应的结构体，比盲猜效率高得多。
对于来源不可控的JSON，比如爬虫抓取的数据或者第三方接口，建议封装一层解析函数，统一处理空数据、非法JSON、类型不匹配三种情况，并记录原始数据片段到日志，方便后续排查。
写出健壮解析代码的几个技巧
第一，善用结构体标签。json:"name,omitempty"不仅能控制序列化行为，也能明确指定解析时匹配的键名，避免依赖默认的大小写不敏感匹配带来的隐患。第二，对于可能缺失或为null的字段，使用指针类型*string、*int64来接收，这样null和零值就能区分开，业务逻辑判断会更清晰。
type User struct {
Name string `json:"name"`
Age *int `json:"age"` // 指针类型，null时为nil
OrderID int64 `json:"order_id"` // 大整数用int64而不是float64
Extra json.RawMessage `json:"extra"` // 延迟解析的字段
}
func (u *User) UnmarshalJSON(data []byte) error {
type Alias User
aux := &struct {
Age json.Number `json:"age"`
*Alias
}{Alias: (*Alias)(u)}
if err := json.Unmarshal(data, aux); err != nil {
return fmt.Errorf("解析User失败: %w", err)
}
return nil
}
第三，大整数场景强烈建议使用json.Number类型，它保留了原始字符串形式，需要时再转换，从根本上避免float64精度丢失。第四，对于结构复杂或需要延迟处理的字段，用json.RawMessage先把原始字节存下来，等真正需要时再解析，既灵活又高效。
最后要强调错误包装的习惯。在自己的解析层函数里，不要直接把error原样抛出去，用fmt.Errorf加上%w包装一层上下文信息，说明是在解析哪个接口、哪份数据时出的错，调用链上层用errors.As依然能拿到原始错误类型。这些细节单独看都很小，但组合起来能让你的JSON解析代码在面对脏数据时稳如磐石，出问题时也能在几分钟内定位到根源。