Go JSON 类型错误怎样定位字段和输入偏移

接口返回的 JSON 能被解析，不代表每个字段都成功落到了目标结构体。最容易误判的一类情况是：json.Unmarshal 返回了错误，但部分字段已经填充，日志里只有一行很长的字符串，真正的问题字段却不明显。

这时不要继续拆错误文本。把错误转换成 *json.UnmarshalTypeError，重点看 Field 和 Offset：前者告诉你结构体路径，后者告诉你输入字节位置；Value 与 Type 则说明“收到的 JSON 值”和“期待的 Go 类型”分别是什么。

定位 JSON 类型错误的最短路径是：先用 errors.As 取出结构化错误，再用 Field 找字段、用 Offset 回看原始字节，最后根据 Value 和 Type 决定修复输入还是修复结构体。

问题现场：先确认不是 JSON 语法错误

语法错误和类型错误要分开处理。缺少逗号、引号没有闭合时，通常得到的是 *json.SyntaxError；JSON 语法正确，但字符串无法放进 int、数组无法放进结构体字段时，才属于 *json.UnmarshalTypeError。

先做类型断言，日志里保留原始错误作为兜底。这样以后即使标准库调整错误文本，排障代码仍然依赖稳定字段，而不是依赖字符串切割。

package main

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

func main() {
    data := []byte(`{"user":{"name":"Ada","age":"37"},"enabled":true}`)

    var payload struct {
        User struct {
            Name string `json:"name"`
            Age  int    `json:"age"`
        } `json:"user"`
        Enabled bool `json:"enabled"`
    }

    err := json.Unmarshal(data, &payload)
    if err == nil {
        return
    }

    var typeErr *json.UnmarshalTypeError
    // errors.As 负责沿错误链寻找结构化的类型错误。
    if errors.As(err, &typeErr) {
        // 四个字段分别回答：收到什么、要什么、在哪个字段、输入到哪里。
        fmt.Printf("value=%s type=%v field=%s offset=%d\\n",
            typeErr.Value, typeErr.Type, typeErr.Field, typeErr.Offset)
        return
    }

    // 语法错误或其他错误仍保留完整错误信息，便于区分排查方向。
    fmt.Printf("json decode failed: %v\\n", err)
}

这个示例中，age 的 JSON 值是字符串，而目标字段是 int。不要把 Field 当成 JSON 文本中的原始键名来猜，直接记录标准库返回的完整字段路径；嵌套结构出现时，它比只看最后一个字段名更可靠。

初步判断：Field、Value 和 Type 各自回答什么

UnmarshalTypeError 的几个字段不要混在一起看。排错时可以按下面的顺序阅读：

Value 和 Type 组合起来通常已经能判断契约哪一侧出了问题：例如 Value 表示字符串、Type 表示整数，优先检查上游是否把数字序列化成了带引号的文本；如果接口长期允许两种形态，再考虑使用自定义解码策略，而不是在日志层掩盖差异。

动手验证：用 Offset 回到原始 JSON

Offset 是字节偏移，不是 Unicode 字符下标，也不是天然的行列坐标。输入中含中文时，一个字符可能占多个字节，所以不要直接把它交给按字符计数的函数。最稳妥的做法是把原始 []byte 保留下来，围绕偏移截取一小段上下文。

package main

import "fmt"

func showJSONContext(data []byte, offset int64) string {
    // Offset 表示读到该位置后的字节数，先把范围限制在原始输入内。
    end := int(offset)
    if end  len(data) {
        end = len(data)
    }

    start := end - 24
    if start 

在生产日志中可以同时打印 Field、Value、Type 和上下文片段，但要先脱敏。JSON 可能包含手机号、令牌或业务正文，定位能力不应该变成敏感数据泄露。

如果输入是格式化 JSON，还可以用 data[:offset] 统计换行符得到近似行号；这个行号只对当前原始字节串有效。经过压缩、重新编码或拼接后，原偏移就不能继续套用。

定位原因：嵌套 Field 和 Offset 要一起看

当错误字段位于多层对象或数组中，Field 负责回答“目标结构体的哪条路径”，Offset 负责回答“输入字节串的哪一带”。两者用途不同，不能互相替代：

• Field 很清楚、Offset 附近内容不符合预期：通常是上游字段值类型变化。
• Offset 附近已经是预期数据、Field 却指向意外字段：检查结构体标签、嵌套类型和输入版本。
• 两者都指向正确位置：再比较 Value 与 Type，决定改调用方契约还是改接收类型。

排查数组时还要注意：字段路径能帮助定位对象字段，但它并不等于一套通用的“数组下标语法”。不要自行拼接不存在的路径格式；需要具体元素时，结合 Offset 片段和业务请求中的数组顺序一起判断。

修复方案：不要忽略类型错误后的部分填充

json.Unmarshal 遇到不适合目标类型的值时，会尽可能继续处理，并返回最早遇到的类型错误；文档同时提醒，错误字段之后的字段不保证都已经完成解码。这意味着“返回了错误”和“目标对象完全为空”不是一回事。

如果输入来自不可信客户端或跨服务契约，建议把非 nil 错误视为整条请求失败，不要把已经填充的对象继续写入数据库。若业务确实允许部分成功，则应显式设计字段级错误报告，并在后续逻辑中区分“缺省值”和“未解码”。

func decodePayload(data []byte) (Payload, error) {
    var payload Payload
    if err := json.Unmarshal(data, &payload); err != nil {
        var typeErr *json.UnmarshalTypeError
        // 返回结构化诊断，但不把可能只填充了一半的 payload 交给业务层。
        if errors.As(err, &typeErr) {
            return Payload{}, fmt.Errorf("字段 %s 类型不匹配：%w", typeErr.Field, err)
        }
        return Payload{}, fmt.Errorf("JSON 无法解析：%w", err)
    }
    return payload, nil
}

这里的关键不是把错误包装得更长，而是失败时返回零值对象，避免调用方误以为所有字段都已可靠解析。需要保留诊断时，用日志字段记录 Field 和 Offset，用错误链保留原始原因。

验证结果：一张速查表收口

总结一下：Field 是结构体路径，Offset 是原始输入的字节位置，Value 和 Type 负责解释不匹配的两端。把四个字段放在同一条诊断记录里，通常比打印一整行错误字符串更快找到真正的契约问题。

相关问题

类型错误和语法错误可以用同一套判断吗？

不建议。先用 errors.As 区分 *json.UnmarshalTypeError 与 *json.SyntaxError，两者的修复方向不同。

Offset 是字符位置还是字节位置？

按原始输入的字节数理解。UTF-8 文本存在多字节字符时，不能直接当成字符下标。

拿到类型错误后还能使用已经解析出的字段吗？

默认不要。标准库会尽力继续处理，但错误字段之后的字段不保证完成解析；除非业务明确设计了部分成功语义，否则应丢弃这次结果。