Go encoding/json.Decoder InputOffset 怎么定位坏 JSON：字节偏移、UTF-8 与错误行号

线上配置接口返回 400 时，日志里只有“invalid character”通常不够用：你还需要知道坏字节落在哪一行、哪一列，以及这个位置是字节偏移还是用户看到的字符序号。Go 的 encoding/json 已经提供了两条线索：语法错误可以读取 json.SyntaxError.Offset，流式解码则可以用 Decoder.InputOffset() 取得当前输入流的字节位置。

先把错误位置分成两种偏移

encoding/json 的位置定义很明确，但日志代码经常把它改成“字符下标”，结果反而偏一位。SyntaxError.Offset 是错误附近的输入字节偏移，Decoder.InputOffset() 返回最近一次返回的 token 末尾、下一个 token 开始附近的输入字节偏移。二者都不能直接拿来索引 Go 字符串的 rune。

单次解析：从 SyntaxError.Offset 截取上下文

先保留原始字节，再做偏移计算。不要先把请求体转换成 rune 切片，否则拿到的偏移已经失去原始字节语义。

package main

import (
    "encoding/json"
    "fmt"
)

func main() {
    raw := []byte(`{"name":"北京","port":8080,}`)
    var v map[string]any
    if err := json.Unmarshal(raw, &v); err != nil {
        if se, ok := err.(*json.SyntaxError); ok {
            pos := int(se.Offset) - 1 // Offset 按文档语义换成 0 基字节索引
            if pos  len(raw) { pos = len(raw) }
            left, right := pos-12, pos+12
            if left  len(raw) { right = len(raw) }
            fmt.Printf("json error byte=%d context=%q\n", se.Offset, raw[left:right])
        }
    }
}

这个例子把偏移转换成上下文窗口，而不是直接输出整份请求体。日志中还可以补充请求 ID、字段名和解析阶段；配置内容本身如果可能包含密钥，应先脱敏。

流式 Decoder：记录每次 Decode 前后的边界

对连续 JSON 对象，Decoder 可能提前从底层 reader 读取更多字节，所以“底层 reader 已读到哪里”和“最近 token 的逻辑位置”不是一回事。业务日志要记录的是 decoder 的位置，并把每个对象的序号一起写进去。

dec := json.NewDecoder(r)
for index := 1; ; index++ {
    before := dec.InputOffset()
    var item Request
    err := dec.Decode(&item)
    after := dec.InputOffset()
    if err == io.EOF {
        break
    }
    if err != nil {
        log.Printf("decode item=%d before=%d after=%d err=%v", index, before, after, err)
        break
    }
    log.Printf("decode item=%d bytes=%d", index, after-before)
    handle(item)
}

如果错误发生在当前对象内部，after 不一定会推进到错误字节；这时应优先解析错误类型中的偏移信息。before 和 after 更适合回答“哪一个对象开始出问题”和“成功对象大约消耗了多少输入”。

中文、emoji 与行列号不要混算

开发者在日志里最容易踩的坑，是把字节偏移当成字符串下标。下面的辅助函数按原始字节找行，再把当前行的 UTF-8 片段转换成可读列号；列号从 1 开始，适合展示给人看。

func lineColumn(raw []byte, offset int64) (line, column int) {
    if offset  len(raw) { end = len(raw) }
    line = 1
    lineStart := 0
    for i, b := range raw[:end] {
        if b == '\n' {
            line++
            lineStart = i + 1
        }
    }
    column = utf8.RuneCount(raw[lineStart:end]) + 1
    return line, column
}

这里的 column 是按 rune 计算的展示列，不等同于终端的视觉宽度：全角字符、组合音标和某些 emoji 可能占用不同的屏幕宽度。如果你要对接编辑器，应明确约定使用字节列、rune 列还是 UTF-16 列。

一段可复用的错误报告函数

实际项目里建议把“提取偏移、行列换算、上下文截取”封装起来。错误报告只返回定位信息，不返回原始密文，这样调用方可以决定哪些字段适合写入日志。

type JSONLocation struct {
    Offset int64
    Line   int
    Column int
}

func locateJSON(raw []byte, err error) (JSONLocation, bool) {
    se, ok := err.(*json.SyntaxError)
    if !ok { return JSONLocation{}, false }
    line, column := lineColumn(raw, se.Offset)
    return JSONLocation{Offset: se.Offset, Line: line, Column: column}, true
}

如果服务端还需要区分类型错误、未知字段和语法错误，可以分别处理 *json.UnmarshalTypeError、SyntaxError 与 DisallowUnknownFields 返回的错误。不要把所有错误都标成“JSON 格式错误”，否则排查入口会被混淆。

常见问题

InputOffset 返回的是字符位置吗？

不是。它描述输入流中的字节偏移；中文、emoji 等多字节内容会让它与 rune 序号不同。

为什么 InputOffset 看起来比错误位置更靠后？

Decoder 可能已经从 reader 预读数据，而且 InputOffset 表示最近 token 的逻辑边界。语法错误本身优先读取 SyntaxError.Offset。

能不能直接把 Offset 用作 raw[offset]？

要先处理 1 基与 0 基差异，并限制在 len(raw) 范围内。示例中的 Offset-1 只用于截取上下文，不代表所有错误类型都有同样字段。

日志里应该打印多少原始 JSON？

只打印有限字节窗口和请求 ID，敏感字段先脱敏；生产环境不建议直接记录完整请求体。

最后的检查清单

• 先判断错误是不是 *json.SyntaxError，再读取 Offset。
• 保留原始 []byte，不要用 rune 切片替代它做偏移计算。
• 把字节偏移、展示行列和请求 ID 分开记录。
• 流式解码同时记录对象序号与 InputOffset，并为上下文窗口设置上限。