Go encoding/json Decoder.InputOffset 如何定位坏字段

用 Go 的 encoding/json.Decoder 解析请求体时，日志里常见的困惑是：明明报错了，Decoder.InputOffset() 却不像“坏字段位置”。原因在于它记录的是解码器当前位置，不是任何错误都能直接映射出的字段名。处理 JSON 语法错误时，先读 json.SyntaxError.Offset；需要观察流式解码进度时，再用 InputOffset 做可靠的游标记录。

先分清两个 offset：一个指向错误，一个记录游标

SyntaxError.Offset 用来描述 JSON 语法错误发生到哪里；而 Decoder.InputOffset 返回当前 decoder 的输入流字节偏移。后者适合在成功读取 token 后记录“已经可靠走到哪里”，不能简单等同于“坏字段的第几个字符”。

最小配方：先用 SyntaxError.Offset 打印错误附近片段

对于一次性的 JSON 请求，先把输入保留为字节切片，再从错误偏移附近截取一小段上下文。这样既能看到原始字符，也不会误把多字节 UTF-8 文本当成单字节字符处理。

package main

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

func contextAt(src []byte, offset int64) []byte {
    // Offset 按 JSON 输入的字节位置理解；这里仅截取附近窗口用于日志。
    pos := int(offset) - 1
    if pos  len(src) {
        end = len(src)
    }
    return src[start:end]
}

func locate(src []byte) {
    var payload map[string]any
    dec := json.NewDecoder(bytes.NewReader(src))
    if err := dec.Decode(&payload); err != nil {
        var syntaxErr *json.SyntaxError
        if errors.As(err, &syntaxErr) {
            // SyntaxError.Offset 用于指出语法错误附近的输入字节位置。
            fmt.Printf("syntax offset=%d context=%q\\n", syntaxErr.Offset, contextAt(src, syntaxErr.Offset))
        }
        // 这个值是 decoder 游标，不能直接当作业务字段名的位置。
        fmt.Printf("decoder offset=%d error=%v\\n", dec.InputOffset(), err)
    }
}

示例中还需要在 import 里加入 bytes。日志里同时打印两个值，是为了让排查者看出“错误报告位置”和“解码器当前游标”的差异。如果错误来自类型不匹配而不是 JSON 语法，重点应转向 json.UnmarshalTypeError 的字段和结构信息，而不是强行读取 SyntaxError。

流式 JSON 用 InputOffset 记录最后一个可靠 token

当输入是连续 JSON 值或需要逐 token 诊断时，可以先记录每次成功返回的 token，再在出错时打印最后一个 token 和当前偏移。这样定位范围会稳定很多。

dec := json.NewDecoder(r)
for {
    token, err := dec.Token()
    if err == io.EOF {
        break
    }
    if err != nil {
        // 失败时保留最近一次成功 token 和 decoder 游标，便于缩小范围。
        return fmt.Errorf("after token %v at byte %d: %w", lastToken, dec.InputOffset(), err)
    }
    // InputOffset 指向最近返回 token 的结束处和下一个 token 的开始处。
    lastToken = token
    log.Printf("token=%v next=%d", token, dec.InputOffset())
}

这里的 InputOffset 是字节偏移，不是 rune 索引；输入里有中文或 emoji 时，切片窗口仍应按字节边界处理。若需要展示给用户，先保留原始字节，再做安全的字符串转换。

三个容易误判的边界

1. 偏移不是字段名：JSON 只有字节位置，字段名需要结合上下文或 token 路径自行维护。
2. 偏移不是字符数：UTF-8 下一个中文可能占多个字节，展示位置时不要直接把 byte offset 当字符串下标。
3. 缓冲不是已验证内容：Decoder 可能提前从底层 reader 读取数据，InputOffset 反映解析位置，不代表底层 reader 只读到了这里。

常见问题

InputOffset 为什么和错误提示里的位置不一样？

两者语义不同。语法错误优先看 SyntaxError.Offset；InputOffset 是 decoder 当前解析游标，尤其在缓冲或 token 流中不一定等于错误字节。

能不能直接用 offset 截取字符串？

不建议。offset 是输入字节位置，先在 []byte 上截取，再处理 UTF-8 展示，避免从多字节字符中间切开。

如何定位到具体 JSON 字段？

语法错误只能先定位字节范围；要得到字段路径，需要在 Token 遍历时维护对象键和数组索引，或让上层解析结构补充字段上下文。

记住一句话：SyntaxError.Offset 用来追语法错误，InputOffset 用来记 decoder 游标。把偏移量、最近 token 和附近原始字节一起写进日志，才是可复用的 JSON 排障信息。