当前位置：首页 > 文章列表 > Golang > Go问答 > Go json.Decoder.Buffered 接回预读字节的流式处理方案

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

来源：17golang原创 2026-10-31 19:28:08 0浏览收藏

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

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

要点速览

Buffered() 返回的是 Decoder 内部已经读入、但尚未被消费的字节，不是整个原始输入。
它只适合在最近一次 Decode 或 Token 后马上读取；下一次 Decoder 操作会让这段交接关系失效。
将 Buffered 与原始 Reader 用 io.MultiReader 拼接，才能避免跳过预读内容或重复读取。

Buffered 解决的是哪一段数据

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

数据位置	能否从 Buffered 取回	处理建议
已完成 Decode 的 JSON 值	不能	从目标变量使用
Decoder 已预读但未消费的尾部	可以	立即保存并交给后续 Reader
底层 Reader 尚未读取的部分	不在 Buffered 中	继续读取原始 Reader

Go json.Decoder、底层 Reader 与 Buffered 预读字节的边界关系说明图 — 图1：结构说明图，展示 Go json.Decoder 已消费 JSON、内部 Buffered 尾部与底层 Reader 的边界。

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

下面的例子把一个 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 元数据 + 二进制载荷”等边界清楚的协议。

Go Buffered 与 io.MultiReader 交接尾部协议数据的静态关系图 — 图2：操作示意图，展示 Buffered 尾部先进入 io.MultiReader，再与底层 Reader 拼接给后续解析器。

迁移时要改的三个边界

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

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

回归检查与适用场景

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

输入	期待结果
JSON 后有自定义尾部	尾部按原顺序完整交给后续读取器
JSON 后没有字节	尾部为空，不把 EOF 当成业务数据
尾部只到半个记录	后续解析器报告截断，不能静默成功
JSON 头部非法	Decode 返回错误，不进入 Buffered 交接

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