Go encoding/json Decoder.Token 怎么解析混合结构：流式游标、Delim 与提前结束

日志采集服务收到一段 JSON 时，字段顺序和数组长度经常不固定；如果为了找一个嵌套字段先把整段内容反序列化成大结构，内存和容错边界都会变得模糊。Go 的 encoding/json.Decoder.Token 适合处理这种“沿着结构走”的场景：它把输入变成连续令牌，遇到对象或数组边界时用 json.Delim 表示，真正的值再交给 Decode。

记住一条实用规则：先用 Decoder.Token 看清结构，再用 dec.More 控制容器内循环；读到顶层结束后仍要区分正常的 io.EOF 和语法错误。

为什么混合 JSON 更适合流式游标

假设输入是一个批次对象，里面有 events 数组，每个事件包含固定的 kind 和不固定的 payload。我们只想处理 kind=warning 的事件，不需要把所有 payload 映射成同一个 Go 类型。

type Warning struct {
    Kind    string          `json:"kind"`
    Payload json.RawMessage `json:"payload"`
}

func readWarnings(r io.Reader) ([]Warning, error) {
    dec := json.NewDecoder(r)
    tok, err := dec.Token()
    if err != nil { return nil, err }
    if delim, ok := tok.(json.Delim); !ok || delim != '{' {
        return nil, fmt.Errorf("root must be object")
    }

    var out []Warning
    for dec.More() {
        key, err := dec.Token()
        if err != nil { return nil, err }
        field, ok := key.(string)
        if !ok { return nil, fmt.Errorf("object key is not string") }
        if field != "events" {
            var ignored json.RawMessage
            if err := dec.Decode(&ignored); err != nil { return nil, err }
            continue
        }
        start, err := dec.Token()
        if err != nil { return nil, err }
        if delim, ok := start.(json.Delim); !ok || delim != '[' {
            return nil, fmt.Errorf("events must be array")
        }
        for dec.More() {
            var item Warning
            if err := dec.Decode(&item); err != nil { return nil, err }
            if item.Kind == "warning" { out = append(out, item) }
        }
        if _, err := dec.Token(); err != nil { return nil, err }
    }
    if _, err := dec.Token(); err != nil { return nil, err }
    return out, nil
}

这里的游标顺序很重要：根对象的 { 由 Decoder.Token 读出，字段名仍由 Decoder.Token 读取，events 的数组边界由 json.Delim 确认，数组成员才交给 Decode。每一次调用都检查错误，避免游标停在半个结构上还继续处理。

json.Delim 与 dec.More 要配对使用

json.Delim 只告诉你当前令牌是 {、}、[ 还是 ]；它不会替你消费容器内容。进入 events 后，dec.More 判断数组里是否还有成员，循环结束后再用一次 Decoder.Token 消费 ]。

最容易出错的是把 dec.More 当成“下一次读取一定成功”。网络流被截断时，dec.More 后面的 Decode 仍可能返回错误；所以成员读取、结束分隔符读取都必须检查返回值。

只读一个目标字段时怎么提前结束

如果业务只关心第一个 warning，可以在成功 Decode 后停止自己的业务循环，但要明确这是“业务提前结束”，不是 JSON 已经读完。连接复用、请求体关闭或后续校验由调用方负责，不要把提前返回伪装成完整解析成功。

顶层结束与损坏输入的区别

Decoder.Token 和 Decode 处理流时，顶层内容完整读完后再次读取，通常用 io.EOF 表示没有更多 JSON 值；这和中途出现的 syntax error（语法错误）不是一回事。若输入在数组成员中断开，应该返回错误，让上游决定丢弃批次还是重试。

for {
    tok, err := dec.Token()
    if errors.Is(err, io.EOF) {
        break
    }
    if err != nil {
        return fmt.Errorf("read token: %w", err)
    }
    // 根据 tok 的类型继续处理
}

验收时可以准备三组数据：完整对象、events 缺少结束括号的截断对象、以及根节点不是对象的输入。第一组应返回目标事件，第二组应保留非 EOF 错误，第三组应在根 json.Delim 校验处失败。

常见问题

Decoder.Token 能直接返回一个业务结构体吗？

不能。它返回 JSON 令牌；业务对象应使用 Decoder.Decode 或先取值再转换。

dec.More 需要单独判断错误吗？

需要。它只表示当前容器是否还有成员，后续的 Token 或 Decode 仍必须检查错误。

为什么不把所有字段都写进结构体？

字段层级或 payload 类型不稳定时，令牌定位能缩小映射范围；结构固定且需要完整校验时，直接使用结构体反而更清楚。

把游标边界写进测试

流式解析的可靠性不在于代码短，而在于每个 json.Delim、dec.More 和 io.EOF 都有明确含义。先覆盖完整、空数组和截断输入，再决定是否在业务上提前结束，排查时会比追踪一个大结构体的零值更直接。