Go 怎么把 JSON 解码错误定位到输入上下文

Go 的 JSON 解码报错要定位到输入上下文，关键不是把 err.Error() 原样打到日志里，而是先识别错误类型，再按正确口径使用偏移量。语法问题通常从 *json.SyntaxError.Offset 找附近字节；目标类型不匹配则读取 *json.UnmarshalTypeError 的 Field 和 Offset。如果使用 json.Decoder 处理连续输入，InputOffset() 表示流当前位置，还要配合记录序号或业务键。

一、先分清错误类型和偏移口径

encoding/json 的错误至少要分两类看。JSON 少逗号、引号未闭合或出现非法字符时，返回的通常是 *json.SyntaxError，它的 Offset 表示错误发生在读过多少字节之后。JSON 语法正确，但字符串、数字与目标 Go 类型不匹配时，常见的是 *json.UnmarshalTypeError，除了 Offset，还会提供 Value、Type、Struct 和 Field。

两者的偏移都是字节口径，不是字符位置，也不是从零开始的数组下标。输入含中文时，不能直接用字符串的 rune 数去切片；需要在原始 []byte 上计算。可以先把信息整理成这张速查表：

二、用错误类型还原字段上下文

排障函数可以用 errors.As 保留具体错误类型，再从原始字节中截取一个有限窗口。下面的示例只展示定位逻辑，窗口大小按业务日志长度调整：

package main

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

func errorContext(raw []byte, err error) string {
    var syntaxErr *json.SyntaxError
    var typeErr *json.UnmarshalTypeError
    var offset int64
    kind := "JSON 解码失败"
    field := ""

    // 先判断具体错误类型，避免只依赖不稳定的错误字符串。
    switch {
    case errors.As(err, &syntaxErr):
        offset = syntaxErr.Offset
        kind = "JSON 语法错误"
    case errors.As(err, &typeErr):
        offset = typeErr.Offset
        field = typeErr.Field
        kind = "JSON 类型错误"
    default:
        return fmt.Sprintf("%s：%v", kind, err)
    }

    // Offset 表示读过的字节数，转换成 []byte 下标时减一。
    pos := int(offset - 1)
    if pos  len(raw) {
        end = len(raw)
    }
    return fmt.Sprintf("%s field=%q offset=%d near=%q", kind, field, offset, raw[start:end])
}

这里的 near 是帮助人快速定位的局部片段，不应被当成完整请求体。生产日志还应限制窗口长度、按接口或租户脱敏，并记录请求 ID。若错误被包装过，errors.As 仍能沿包装链找到具体类型；若是底层读取错误，则应保留原始错误，不强行添加 JSON 偏移。

三、流式解码时补上记录范围

当输入是多个连续 JSON 值或来自网络流时，Decoder.InputOffset() 很有用：它表示最近返回 token 的末尾与下一个 token 开始之间的输入字节边界。它反映 Decoder 已经走到哪里，不能简单当作嵌套字段的精确错误下标。

因此，流式日志至少组合三项：当前记录序号、业务键、InputOffset()。如果每条记录本身还要定位字段，再把该条记录暂存为字节切片后单独解码；不要只打印整个长连接的全局 offset。

dec := json.NewDecoder(reader)
for recordNo := 1; ; recordNo++ {
    var event Event
    err := dec.Decode(&event)
    if err == io.EOF {
        break // 正常结束输入，不作为业务错误记录。
    }
    if err != nil {
        // InputOffset 是流边界；recordNo 和业务键补足可检索上下文。
        log.Printf("json decode failed record=%d offset=%d key=%q err=%v", recordNo, dec.InputOffset(), event.ID, err)
        break
    }
}

四、把定位信息写进业务日志

一条能真正帮助排查的日志，建议固定字段而不是拼一大段字符串：error_kind、field、offset、record_no、request_id 和受限的 near。这样可以按字段筛选“某接口的类型错误”，也能把语法错误和上游网络截断区分开。

排查时按这个顺序核对：先确认原始字节是否完整，再看错误具体类型；随后检查 Offset 是否被误当成字符下标，最后判断流式场景是否缺少记录边界。不要用 strings.Index 直接按字段名猜位置，因为同名字段、转义字符串和重复数组项都会让结果失真。

常见问题

为什么 JSON 有中文时截取片段会错位？

因为偏移按 UTF-8 字节计算，而不是按 Go 字符数计算。应保留原始 []byte，在字节切片上截取。

UnmarshalTypeError.Field 为空怎么办？

它可能来自顶层值、非结构体目标或自定义解码逻辑。此时保留 Value、Type、Offset，并结合调用方的业务键定位。

InputOffset() 能直接指出坏字段吗？

不能一概而论。它首先是 Decoder 的流位置；字段级问题仍应优先读取具体错误对象的字段和偏移。