Go encoding/json.Decoder 为什么会吞掉下一个 JSON：流式边界、Token 读取与多对象解析

排查一个批量导入接口时，日志里出现了两个紧挨着的 JSON 对象：第一轮 Decode 成功，第二轮却像是“少读了一个字段”。这类问题通常不是 encoding/json 把下一个对象吞掉了，而是把 Decoder 当成了“每次只看一个独立字符串”的解析器，忽略了它维护的流式读取位置。

先把“吞掉下一个 JSON”的现场固定下来

先不要在业务结构体上反复改字段。下面的输入没有换行，两个对象直接相邻，正好模拟日志流、HTTP 长连接或批量文件里常见的连续 JSON：

src := strings.NewReader(`{"id":1,"name":"alpha"}{"id":2,"name":"beta"}`)
dec := json.NewDecoder(src)

var first, second Item
err1 := dec.Decode(&first)
err2 := dec.Decode(&second)
fmt.Println(first, err1)
fmt.Println(second, err2)

两次 Decode 都能成功，原因是 JSON 值之间不要求必须有空格；对象结束后，解码器会继续从内部游标读取下一个值。真正值得记录的是每次调用返回的错误，以及调用前后业务变量是否被复用。

为什么混用 Token 和 Decode 时最容易误判

Token 返回的是流中的下一个 JSON token，例如 {、字段名、字符串值和 }。它不是“预览下一个对象”的无副作用方法；调用一次就会推进一次游标。随后再调用 Decode，它只能从当前位置继续。

tok, err := dec.Token()
if err != nil {
    return err
}
fmt.Printf("first token: %#v\n", tok)

// 此时游标已经进入对象内部，不能再把整个对象当作完整值从当前位置 Decode。

如果只是想连续读取对象，统一使用 Decode 更容易验证。只有需要遍历未知结构、检查数组/对象边界或做流式过滤时，才把 Token 作为主读取接口，并明确维护当前层级。

用错误类型确认流到底结束在哪里

连续对象解析的循环不要用“目标结构体是否还是零值”判断结束。字段缺失、合法的空对象和真正的输入结束不是一回事：

for {
    var item Item
    err := dec.Decode(&item)
    switch {
    case err == nil:
        fmt.Printf("accepted id=%d name=%q\n", item.ID, item.Name)
    case errors.Is(err, io.EOF):
        return nil
    default:
        return fmt.Errorf("decode item: %w", err)
    }
}

这里的检查点有两个：第一，io.EOF 只代表没有更多 JSON 值；第二，语法错误、类型错误和业务校验错误都应该保留，不能被统一当成“循环结束”。这样日志才能区分半截请求和正常收尾。

Buffered 看到的是什么，不能拿它代替 Decode

Decoder 可能为了完成当前值而提前从底层 io.Reader 读入更多字节。那些已经读入但还没有被当前值消费的内容，会留在内部缓冲中。Buffered 返回的就是这部分尾部视图：

var item Item
if err := dec.Decode(&item); err != nil {
    return err
}
tail, err := io.ReadAll(dec.Buffered())
if err != nil {
    return err
}
fmt.Printf("decoded=%+v buffered-tail=%q\n", item, tail)

尾部字节属于解码器内部已读数据，适合做诊断或把剩余内容交给另一个明确的读取流程。不要在同一条流上同时拿底层 Reader 和 Buffered 猜谁拥有当前位置，否则很容易得到顺序错乱的结果。

三种现场对应的处理方式

如果第二次解析报错，先把每次读取的错误、结构体值和剩余字节记录下来，再判断是输入不完整、Token 已经推进过游标，还是调用方把同一个 Decoder 错误地复用了。

常见问题：到底该选哪种读取方式

两个 JSON 之间必须加换行吗？

不必须。只要前一个值已经完整结束，Decoder 可以继续读取后一个值；换行只是让日志更易读。

第二次 Decode 返回 EOF 是数据丢了吗？

如果第一次 Decode 已经成功且输入确实只有一个值，第二次得到 EOF 是正常结束。只有在发送方声称还有更多对象时，才需要检查上游是否提前截断。

Token 能和 Decode 混用吗？

可以，但必须把它们当作共同推进同一个游标的操作。若目标是连续对象，统一用 Decode 通常更清楚。

Buffered 读完后还能继续 Decode 吗？

不应把 Buffered 返回的内容当作已经回写到底层的输入。要继续由原 Decoder 解析，就不要提前消费这段缓冲；需要交接时，应把职责和剩余数据明确分给新的读取流程。

最后用一条最小验收标准收尾

给连续 JSON 的解析器加测试时，至少覆盖：一个对象、两个相邻对象、对象之间带空白、半截对象、字段类型错误，以及 Token 已推进后再 Decode 的行为。每个用例都检查返回错误和读取数量，不只检查最后一个结构体的值。这样当接口从单对象改成流式批量输入时，所谓“吞掉下一个 JSON”就能被还原成一个明确的游标边界问题。