jsontext遇到无效Token如何定位

Go 的 encoding/json/jsontext 把 JSON 当作 Token 和 Value 的语法流处理。遇到“无效 Token”时，先不要把问题归因于结构体字段：多数情况发生在 JSON 字节、引号/转义或 Decoder 当前状态；只有确认语法流有效后，才进入 encoding/json/v2 的语义解码。

官方地址：https://pkg.go.dev/encoding/json/jsontext

先判断是 Token 内容错，还是放置位置错

jsontext.Token代表一个词法单元：null、布尔值、字符串、数字，以及对象或数组的开始/结束分隔符。逗号和冒号不单独生成 Token，它们由周围的结构状态推断。因此同一个 Token 可能“内容正确但位置非法”：例如对象已经结束后继续写字段名，或数组中缺少值。

排查时把问题拆成三层：原始输入是否被截断；Token 是否由正确的构造函数生成；Decoder/Encoder 当前是否期待值、名称或结束分隔符。这样能避免用结构体标签去修复一个尚未通过语法层的问题。

用最小读取片段保留无效位置

读取流时，先看下一个 Token 的 Kind，再决定读取 Token 还是完整 Value。错误一旦出现就保留原始输入和偏移；不要在错误后继续调用多个读取方法，因为 Decoder 可能已经预读了内容，后续日志会掩盖第一现场。

package main

import (
    "fmt"
    "strings"

    "encoding/json/jsontext"
)

func locate(input string) error {
    dec := jsontext.NewDecoder(strings.NewReader(input))
    for {
        kind, err := dec.PeekKind()
        if err != nil {
            // PeekKind 失败时保留当前输入；这里不要继续推进 Decoder。
            return fmt.Errorf("peek kind near offset %d: %w", dec.InputOffset(), err)
        }
        if kind == 0 {
            // 读取到输入结束，说明前面的 Token 已经形成完整语法流。
            return nil
        }
        tok, err := dec.ReadToken()
        if err != nil {
            // ReadToken 的错误通常对应字节、转义或当前语法状态。
            return fmt.Errorf("read token near offset %d: %w", dec.InputOffset(), err)
        }
        fmt.Printf("kind=%q token=%s\\n", tok.Kind(), tok)
    }
}

这里的关键不是打印多少日志，而是把 PeekKind、ReadToken 和偏移绑定在同一条记录里。若错误出现在字符串中间，重点检查反斜杠转义和未闭合引号；若出现在结构边界，重点检查对象/数组的开始与结束是否成对。

写入侧要检查 Token 与当前状态

如果错误来自 Encoder.WriteToken，不要只检查 Token 的打印结果。编码器会维护 JSON 语法状态，合法 Token 放到错误位置同样会返回 SyntacticError，而状态不会因为这个非法写入被推进。

enc := jsontext.NewEncoder(&buf)
for _, tok := range tokens {
    if err := enc.WriteToken(tok); err != nil {
        // 记录失败 Token 和输出偏移，便于重放同一组输入。
        return fmt.Errorf("write %s at offset %d: %w", tok, enc.OutputOffset(), err)
    }
}

最小复现应只保留失败前的几个 Token。例如先写 BeginObject，再写一个字符串名称、一个值，最后写 EndObject；逐步删减后，能判断是 Token 本身不合法，还是名称/值/结束符的顺序不符合语法。

四项检查清单

常见问题

Token 无效是不是结构体字段类型不匹配

不一定。Token 属于语法层，字段类型不匹配通常要等语法读取成功后才出现；先分离两类错误。

为什么日志里看不到逗号和冒号

它们不是独立 Token，而是由 JSON 周围的结构状态推断，所以应检查相邻 Token 的组合。

读取错误后还能继续调用 ReadToken 吗

排障阶段不建议。先保存输入和偏移，继续读取可能让真正的首个错误变得不可见。

什么时候该改用 ReadValue

当业务需要保留一个完整 JSON 值再交给上层语义解码时使用；只定位语法边界则优先逐 Token 读取。

最终修复应落到可复现的输入样本：保存失败前后的 Token、输入偏移和错误类型，回归时再验证同一语法边界。这样“无效 Token”就从笼统报错变成了可定位的输入、状态或构造问题。