Go json.Decoder.Buffered 接回预读字节的流式处理方案

我在处理“JSON 头部后面紧跟一段自定义数据”的输入时，最容易误判的是底层 io.Reader 的当前位置：json.Decoder.Decode 返回，并不代表底层 Reader 只读到了这个 JSON 值的末尾。Decoder 可能已经预读了一部分后续字节。正确的交接方式是，在下一次调用 Decoder 之前立即取得 Buffered()，再把它和底层 Reader 拼成一个连续读取器。

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

Buffered 解决的是哪一段数据

Decoder 内部有自己的缓冲区。一次 Decode 可能把 JSON 值以及后面的若干字节一起读进来，但只把前者交给目标变量。此时数据被分成三段：目标变量已经拿到的值、Decoder 缓冲中尚未消费的字节、底层 Reader 尚未交给 Decoder 的字节。Buffered() 只负责第二段。

把预读缓冲安全交回后续解析器

下面的例子把一个 JSON 对象后面的自定义尾部交给另一个读取逻辑。关键不是“强行让 Decoder 少读”，而是承认它可能预读，再把两段 Reader 按原顺序拼起来。Buffered() 返回的 Reader 只在当前 Decoder 状态下有效，所以要在第二次 Decode、Token 或其他 Decoder 操作前完成交接。

package main

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

func main() {
    // JSON 后紧跟自定义尾部，模拟一条需要分段处理的输入流。
    source := strings.NewReader(`{"kind":"event"}TAIL`)
    decoder := json.NewDecoder(source)

    var header struct {
        Kind string `json:"kind"`
    }
    if err := decoder.Decode(&header); err != nil {
        // 头部失败时不要继续消费尾部，直接交给调用方处理错误。
        panic(err)
    }

    // 必须在下一次 Decoder 操作前取得这段尚未消费的缓冲。
    buffered := decoder.Buffered()
    tail, err := io.ReadAll(io.MultiReader(buffered, source))
    if err != nil {
        // MultiReader 会先读 Buffered，再读底层 Reader，顺序不会跳过字节。
        panic(err)
    }
    fmt.Printf("kind=%s tail=%q\n", header.Kind, tail)
}

这里的 io.MultiReader 有两个作用：先排空 Decoder 的内部缓冲，再接着读底层 Reader。即使底层 Reader 已经被 Decoder 读到更后面，字节顺序仍然保持连续。这个组合适合“JSON 头 + 自定义尾部”“JSON 元数据 + 二进制载荷”等边界清楚的协议。

迁移时要改的三个边界

• 时机：把 decoder.Buffered() 放在刚刚成功的 Decode 或 Token 后面，不能先调用 Decoder 读取下一项。
• 生命周期：Buffered 返回的 Reader 不应跨越下一次 Decoder 操作长期保存；要么立即消费，要么立即包装进后续读取器。
• 数据语义：Buffered 中的内容只是“已读入但尚未消费”的字节，可能还没有被 JSON 语法验证。不要把它误当成一个已经完成校验的 JSON 值。

如果头部 JSON 本身解析失败，应该停止交接；如果尾部读取失败，则保留头部已解析结果和尾部错误，别用一个看似正常的空尾部掩盖截断输入。

回归检查与适用场景

迁移旧代码时，我会至少覆盖下面四组输入。它们能区分“尾部确实为空”和“尾部读取失败”，也能发现错误地重复调用 Decoder 的问题。

这个方案的边界也很明确：它解决的是一次 JSON 解码后的字节交接，不是通用的多对象流拆分器。若后续数据仍然是 JSON，通常应重新创建一个 Decoder 读取拼接后的 Reader；若后续是定长或带长度前缀的二进制协议，则交给对应解析器更合适。

相关问题

Buffered 会返回完整原始输入吗？

不会。它只返回 Decoder 已经读入内部缓冲、但尚未消费的部分，尚未被 Decoder 读到的数据仍在底层 Reader 中。

拿到 Buffered 后还能继续 Decode 吗？

不建议把两件事混用。先完成字节交接，再由后续读取器负责剩余数据；下一次 Decoder 操作可能改变这段缓冲的有效边界。

为什么不直接继续读底层 Reader？

因为 Decoder 可能已经把尾部读进自己的缓冲。只读底层 Reader 可能跳过这部分字节，使用 Buffered 加底层 Reader 的组合才能保持连续。