Go json.UnmarshalTypeError 怎样定位类型不匹配字段

Go 调用 json.Unmarshal 后遇到 cannot unmarshal，最有用的动作不是继续放大错误字符串，而是把它断言成 *json.UnmarshalTypeError，读取 Value、Type、Field 和 Offset。这样可以回答“JSON 里是什么值、Go 想把它放进什么类型、具体落在哪个字段、错误大约出现在输入哪里”。

先记住三点：

• JSON 语法本身不合法，优先看 *json.SyntaxError，不是类型错误。
• 类型不匹配时，Value 是输入值的 JSON 类型描述，Type 是目标 Go 类型。
• 解码可能已经写入一部分字段；只有错误处理完成后，结果才适合交给业务层判断。

排查顺序可以固定为：先确认语法，再提取类型错误，接着看字段路径和目标类型，最后用 Offset 回到原始 JSON 定位输入边界。

先区分语法错误和类型错误

这两类错误经常被一起称为“JSON 解析失败”，但处理方向完全不同。缺少逗号、引号未闭合等问题属于语法错误；例如把字符串值解码到 int 字段，则属于类型错误。语法错误连 JSON 结构都没有建立起来，先修输入文本；类型错误则要检查字段定义、上游契约或兼容策略。

package main

import (
    "encoding/json"
    "errors"
    "fmt"
)

type Order struct {
    Count int `json:"count"`
}

func decodeOrder(data []byte) error {
    var order Order
    if err := json.Unmarshal(data, &order); err != nil {
        var typeErr *json.UnmarshalTypeError
        if errors.As(err, &typeErr) {
            // 类型错误进入字段定位分支；不要把它和语法错误混为一谈。
            return fmt.Errorf("字段 %s 的值类型不匹配: %w", typeErr.Field, err)
        }
        return fmt.Errorf("JSON 语法或其它解码错误: %w", err)
    }
    return nil
}

用 errors.As 比直接比较错误字符串稳定。即使上层又包了一层上下文，只要错误链仍然保留，仍可以取出结构化字段。

读取 UnmarshalTypeError 的关键字段

定位时我会先看五个字段。Value 告诉你输入看起来是 string、number、array 等哪一种；Type 告诉你目标字段的反射类型；Field 给出从根对象到出错字段的路径；Struct 是相关结构体名称；Offset 则是读取到输入的哪个字节附近后发现问题。

func explain(data []byte) error {
    var order Order
    err := json.Unmarshal(data, &order)
    if err == nil {
        return nil
    }

    var typeErr *json.UnmarshalTypeError
    if errors.As(err, &typeErr) {
        return fmt.Errorf(
            "value=%s target=%s struct=%s field=%s offset=%d: %w",
            typeErr.Value,
            typeErr.Type,
            typeErr.Struct,
            typeErr.Field,
            typeErr.Offset,
            err,
        )
    }
    return err
}

例如输入 {"count":"3"}，你应先问“接口契约是不是把 count 定义成字符串”，而不是立即把字符串强转成整数。若上游确实允许两种格式，再在字段类型或自定义解码边界上明确处理，避免把兼容逻辑散落在业务代码里。

用最小结构体复现字段边界

真实响应往往很大，直接盯着完整日志容易把字段名、JSON 标签和嵌套层级混在一起。保留出错字段及其父级结构，做一份最小 JSON，通常几分钟就能判断问题是在输入还是模型定义。

type Profile struct {
    Age int `json:"age"`
}

type User struct {
    Profile Profile `json:"profile"`
}

func decodeUser(data []byte) error {
    var user User
    if err := json.Unmarshal(data, &user); err != nil {
        var typeErr *json.UnmarshalTypeError
        if errors.As(err, &typeErr) {
            // 嵌套字段通常可通过完整 Field 路径直接回到请求样本。
            return fmt.Errorf("JSON 字段 %q 需要 %s，收到 %s: %w",
                typeErr.Field, typeErr.Type, typeErr.Value, err)
        }
        return err
    }
    return nil
}

// 最小复现输入：{"profile":{"age":"18"}}

这里的关键不是把错误改成更漂亮的中文，而是确认三个边界：JSON 标签是否写对、目标 Go 类型是否符合接口契约、以及输入值是否被中间层转换过。Offset 适合回看原始字节或长响应，字段路径则更适合业务日志和告警聚合。

处理部分成功和多错误现象

类型错误出现后，Unmarshal 可能跳过当前不匹配字段，继续处理其它字段，但最终通常只返回较早发现的一个类型错误。因此，不能因为某些字段已经填入，就把整个对象当成可信结果；也不要假设一次返回就覆盖了所有坏字段。

工程上更稳妥的做法是：解码失败就记录结构化错误并拒绝提交；如果业务必须收集多个字段错误，就先使用明确的校验层或逐字段策略，而不是依赖标准库一次返回所有类型问题。对于长响应，记录 Field、Value、Type 和 Offset，通常已经足够定位，不必把完整敏感报文写进日志。

一句话总结：UnmarshalTypeError 不是只用来打印报错的字符串，它把“输入是什么、目标要什么、错在哪个字段、读到哪里”都暴露出来。把这些字段保留下来，类型不匹配就能从模糊的接口异常变成可复现的字段问题。

相关问题

为什么只比较错误字符串不可靠？

字符串适合给人看，不适合做稳定分支。字段名称、结构体路径和包裹层变化都可能影响文本；用 errors.As 提取 *json.UnmarshalTypeError 才能继续使用结构化信息。

Offset 是不是出错字段的精确起点？

它表示解码器读取到输入的字节偏移附近，不应简单当成字段文本的起始下标。对长输入可用它缩小范围，再结合 Field 和原始 JSON 判断具体值。

参考资料

Go encoding/json 类型错误文档：https://pkg.go.dev/encoding/json#UnmarshalTypeError

Go 官方 encoding/json 实现：https://go.dev/src/encoding/json/decode.go