Go jsontext Decoder ReadValue 为什么在结束标记处返回错误

如果你在 Go 1.27 的 encoding/json/jsontext 中调用 Decoder.ReadValue，恰好读到对象的 } 或数组的 ]，返回错误通常不是输入损坏，而是读取动作和当前位置不匹配。ReadValue 只能读取一个完整 JSON value；当前位置已经是容器结束标记时，它会返回 *jsontext.SyntacticError，并保持内部状态不变。真正没有更多输入时，才应当把 io.EOF 当作正常结束。

官方文档：https://pkg.go.dev/encoding/json/jsontext

ReadValue 报错的根因：当前位置已经是结束 Token

jsontext 把 JSON 拆成两类读取对象：Token 表示字符串、数字、字面量和容器分隔符；Value 可以表示一个完整的对象或数组。调用 ReadValue 时，解码器希望当前位置存在一个 value。如果当前位置是 EndObject 或 EndArray，它并没有把结束标记当成 value，因此报语法错误。

这里最容易混淆的是两个“结束”：容器结束是 JSON 结构内部的边界，输入结束是 Reader 已经没有字节可读。前者需要让上层循环消费结束 Token，后者才对应 io.EOF。

先用 PeekKind 判断：这里到底还有没有 Value

当读取逻辑不知道当前位置是什么时，先查看下一个 Token 的 kind，再决定是否调用 ReadValue。对象或数组的结束 kind 说明当前层已经完成；普通值、字符串或容器开始标记才可能进入 value 读取分支。

package main

import (
    "fmt"
    "io"

    "encoding/json/jsontext"
)

// readNextValue 只在当前位置不是对象或数组结束标记时读取 Value。
func readNextValue(dec *jsontext.Decoder) (jsontext.Value, error) {
    // PeekKind 只观察当前位置，不抢先消费结束 Token。
    kind, err := dec.PeekKind()
    if err != nil {
        // 没有更多输入时，把 io.EOF 原样交给调用方判断。
        if err == io.EOF {
            return nil, io.EOF
        }
        return nil, err
    }

    // EndObject 和 EndArray 是容器边界，不是一个完整 Value。
    if kind == jsontext.KindEndObject || kind == jsontext.KindEndArray {
        return nil, fmt.Errorf("当前位置是结束标记 %v", kind)
    }

    // 只有确认当前位置能开始一个 Value 后才推进读取状态。
    return dec.ReadValue()
}

这个包装函数的重点不是把所有错误改写成字符串，而是把“观察当前位置”和“推进读取”分开。这样调用方可以把结束标记交给结构解析分支，而不是把一次正常的层级结束误判成损坏数据。

用 ReadToken 消费对象和数组的结束边界

如果当前任务本来就是遍历结构，结束标记应由 ReadToken 读取。可以先用 PeekKind 判断，再读取一个 Token 完成当前层的收尾；不要在发现 EndObject 后继续循环调用 ReadValue。

func consumeContainerEnd(dec *jsontext.Decoder) error {
    // 先观察 kind，避免把普通值误当成容器结束。
    kind, err := dec.PeekKind()
    if err != nil {
        return err
    }
    if kind != jsontext.KindEndObject && kind != jsontext.KindEndArray {
        return fmt.Errorf("当前不是容器结束标记：%v", kind)
    }

    // ReadToken 专门负责消费边界 Token，让解码器进入下一个位置。
    _, err = dec.ReadToken()
    return err
}

对于嵌套对象，外层循环还需要保存当前容器的语义：读到 EndObject 就结束对象分支，读到 EndArray 就结束数组分支。不要用“只要不是 io.EOF 就继续读 Value”这种宽泛条件，因为结构边界本身也会被当成可观察的当前位置。

三种结果应该怎样分别处理

官方文档还特别说明：当 ReadValue 在对象或数组结束位置报告语法错误时，解码器内部状态保持不变。这意味着错误分支不要无条件再次调用同一个方法；应该先改变读取策略，例如消费结束 Token，或者把错误交给当前层级的调用方。

常见误区与排查顺序

• 把 }、] 当成空 Value：它们是 Token，不是 Value。
• 把所有错误都当成 io.EOF：容器边界错误通常意味着循环条件设计不对。
• 报错后直接丢弃一个 Token：先确认当前层级，否则可能跳过下一层真正的数据。
• 混用 Token 和 Value 却不记录状态：对象成员名、数组元素和嵌套容器需要不同的边界处理。

可以按“先 PeekKind、再选 ReadToken 或 ReadValue、最后分类处理 error”的顺序排查。这样既能保留流式读取的低层控制，也不会把正常的 JSON 层级结束包装成异常。

相关问题

ReadValue 返回的 Value 能长期保存吗？ 默认只能使用到下一次 Decoder 的读取动作；需要跨越后续读取时，应按文档要求复制其内容。

为什么不一直使用 ReadToken？ Token 适合结构和词法边界，Value 适合一次取得完整对象或数组；两者组合更适合流式处理。

ReadValue 报错后状态不变有什么用？ 调用方可以在当前位置重新选择边界处理策略，而不是在错误分支中丢失一个尚未消费的结束 Token。