Go json.Decoder.Buffered 怎样读取尚未消费的输入

我第一次在协议流里同时处理 JSON 和后续字节时，误以为 Decode 只会从底层 Reader 取走当前 JSON。实际情况是，json.Decoder 会建立自己的缓冲区，可能提前读入 JSON 值后面的内容。要拿到这部分已经被 Decoder 读取、却还没有被 Decode 或 Token 消费的字节，应在本次解码返回后调用 Buffered()。

官方文档：https://pkg.go.dev/encoding/json#Decoder.Buffered

关键点只有两个：Buffered() 返回的是 Decoder 内部当前未消费的临时 reader；它的有效期到下一次 Decode 或 Token 调用为止。如果还要得到最后一个 JSON 值之后的完整字节，还必须把这个 reader 和底层 Reader 的剩余内容接起来。

先分清 Decoder 与底层 Reader 的消费边界

NewDecoder 接收的是一个 io.Reader，但 Decoder 不承诺每次只读取刚好够当前 JSON 的字节。它可以为了解析而向底层多读一些，于是底层 Reader 的位置可能已经越过了当前值的结尾。

这会形成两个不同的“消费”概念：

• 底层 Reader 消费：字节已经被 Decoder 取到自己的缓冲区。
• Decoder 消费：字节已经被本次 Decode 或 Token 纳入解析。

两者之间的差额就是 Buffered() 试图暴露的部分。它不是把底层 Reader 倒回去，也不是重新解析一份 JSON；它只是把 Decoder 已经读入但尚未交给解析调用的缓冲数据提供成 reader。

在 Decode 返回后读取 Buffered

下面的例子把一个 JSON 对象和后续的分隔文本放在同一条输入里。示例的目的不是模拟某个真实协议，而是把数据边界写清楚：第一段由 Decode 消费，剩余部分先从 Buffered 读取，再读取底层 Reader 尚未交给 Decoder 的部分。

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "strings"
)

type Envelope struct {
    ID   int    `json:"id"`
    Kind string `json:"kind"`
}

func main() {
    // JSON 后面的分隔内容代表协议中尚未处理的下一段字节。
    input := strings.NewReader(`{"id":7,"kind":"event"}--payload--`)
    dec := json.NewDecoder(input)

    var envelope Envelope
    if err := dec.Decode(&envelope); err != nil {
        panic(err)
    }

    // Buffered 只能读取 Decoder 已经取走但尚未交给 Decode 的字节。
    buffered, err := io.ReadAll(dec.Buffered())
    if err != nil {
        panic(err)
    }

    // 底层 Reader 仍可能有未被 Decoder 提前读取的内容，必须一并保留。
    remaining, err := io.ReadAll(input)
    if err != nil {
        panic(err)
    }

    tail := bytes.Join([][]byte{buffered, remaining}, nil)
    fmt.Printf("id=%d kind=%s tail=%q\n", envelope.ID, envelope.Kind, tail)
}

这里的 tail 才代表“最后一个 JSON 值之后的完整输入”。只读取 input，可能漏掉已经进入 Decoder 内部缓冲的字节；只读取 Buffered()，又可能漏掉仍留在底层 Reader 的部分。

把内部缓冲与底层余量重新拼接

拼接顺序不能反过来。Decoder 内部缓冲中的内容位于底层 Reader 当前位置之前，因此应先读 Buffered()，再读底层 Reader。可以把它抽成一个小函数，调用者只负责决定后续如何解释字节。

// readDecoderTail 收集最后一个 JSON 值之后的完整字节。
func readDecoderTail(dec *json.Decoder, source io.Reader) ([]byte, error) {
    // 先读取 Decoder 已经拿到但尚未消费的内部缓冲。
    buffered, err := io.ReadAll(dec.Buffered())
    if err != nil {
        return nil, fmt.Errorf("读取 decoder 缓冲失败: %w", err)
    }

    // 再读取底层 Reader 的剩余内容，维持原始字节顺序。
    remaining, err := io.ReadAll(source)
    if err != nil {
        return nil, fmt.Errorf("读取底层输入失败: %w", err)
    }

    tail := make([]byte, 0, len(buffered)+len(remaining))
    tail = append(tail, buffered...)
    tail = append(tail, remaining...)
    return tail, nil
}

这个函数有一个重要前提：在调用它之前不要再对同一个 Decoder 执行 Decode 或 Token。否则内部缓冲的边界会向前移动，前一次返回的 reader 也不应继续被依赖。

不要把 Buffered 当成已经验证过的 JSON

Buffered() 返回的字节只是 Decoder 已经读进来的数据，并不保证这些字节本身构成合法 JSON。它们可能是下一段协议内容，也可能只是一个尚未完成校验的片段。因此，如果后续逻辑要把它再次当 JSON 使用，应交给新的 Decoder 或其他明确的解析步骤处理，不能仅凭它来自 json.Decoder 就跳过校验。

同样，Buffered() 不是通用的“获取底层剩余文件”接口。它只覆盖 Decoder 当前内部缓冲的部分；底层 Reader 是否还有内容，取决于 Reader 的实际状态。对于网络连接、管道或持续到来的输入，直接 io.ReadAll 还可能一直等待 EOF，调用前要先明确协议的结束条件。

避开下一次 Decode 后的失效边界

官方文档明确规定，Buffered() 返回的 reader 在下一次 Decode 或 Token 调用前有效。最稳妥的做法是：完成一次解码后立即把需要的缓冲内容复制出来，随后再决定是否继续使用 Decoder。

// decodeOneAndKeepTail 先复制尾部，再允许调用方继续处理结果。
func decodeOneAndKeepTail(source io.Reader) (Envelope, []byte, error) {
    dec := json.NewDecoder(source)

    var value Envelope
    if err := dec.Decode(&value); err != nil {
        return Envelope{}, nil, fmt.Errorf("解码 envelope 失败: %w", err)
    }

    // 在下一次 Decode 或 Token 之前复制 Buffered 内容。
    tail, err := readDecoderTail(dec, source)
    if err != nil {
        return Envelope{}, nil, err
    }
    return value, tail, nil
}

如果业务其实是连续 JSON 值，例如一个对象接着另一个对象，那么通常应该继续对同一个 Decoder 调用 Decode，而不是把 Buffered() 当作第二个 JSON 流入口。只有当协议明确要求保留原始尾部、切换到另一种解析器或交给下一层处理时，才适合复制并拼接这些字节。

最后用四个问题判断是否用 Buffered

一句话总结：Decoder.Buffered 解决的是“Decoder 已经从底层取了多少、但解析调用还没消费多少”的边界问题。先在正确时机复制内部缓冲，再接上底层 Reader 的余量；一旦进入下一次 Decode 或 Token，就不要再依赖之前返回的 reader。

相关问题

Buffered 返回的数据一定是完整的下一段 JSON 吗？

不一定。它可能包含未验证的任意字节，完整性和语法都需要由后续协议或解析逻辑决定。

为什么不能只读取底层 Reader？

因为 Decoder 可能已经提前把后续字节读进内部缓冲，底层 Reader 看不到那部分。

什么时候不该使用 Buffered？

如果目标只是逐个解码连续 JSON 值，直接继续调用 Decoder 的 Decode 更简单，也更符合流式解析的边界。