Go bufio.Reader Peek 后读取为什么拿不到完整数据怎样构造最小复现

Go 里调用 bufio.Reader.Peek 后，数据“拿不到完整”通常不是 Peek 把数据吃掉了，而是把三个语义混在了一起：Peek 只返回内部缓冲区的视图，普通 Read 允许短读，而需要固定字节数时应该使用 io.ReadFull。先检查 Peek 的 err 和返回长度，再决定是否继续读取，问题就能稳定复现和修复。

官方地址：https://pkg.go.dev/bufio.Reader

一句话结论：Peek 不推进读取位置，但它返回的切片只在下一次读取前有效；Read 返回多少由 Reader 决定，不能用一次 Read 代替精确读取。

先把 Peek、Read 和 ReadFull 的职责分开

Peek(n) 的目标是“先看接下来的 n 个字节”，它会尝试把数据填入 bufio.Reader 的内部缓冲区，但不会移动读取游标。成功后，后续读操作仍然可以读取这批数据。

容易误判的地方有两个：第一，Peek 返回的字节切片指向内部缓冲区，下一次读操作后就不应继续使用；第二，Peek 返回少于 n 个字节时一定要看错误，不能只看 len(data)。如果请求的数量超过缓冲区容量，返回错误会是 bufio.ErrBufferFull。

最小复现：Peek 没有消费数据，但 Read 仍然可能短读

下面的程序先 Peek 4 个字节，再用一次普通 Read 读取 10 个字节。输入正好有 10 个字节，因此本例可以得到完整结果；把输入缩短，或者把一次 Read 的结果直接当成“已经填满目标切片”，就能复现常见误判。

package main

import (
	"bufio"
	"fmt"
	"strings"
)

func main() {
	// 输入长度为 10，先预览前 4 个字节，但不消耗它们。
	reader := bufio.NewReader(strings.NewReader("0123456789"))
	peeked, err := reader.Peek(4)
	if err != nil {
		// Peek 返回短数据时，错误信息比 len 更重要。
		panic(err)
	}
	fmt.Printf("peek=%q buffered=%d\\n", peeked, reader.Buffered())

	// 普通 Read 只承诺返回本次实际读到的字节数。
	dst := make([]byte, 10)
	n, err := reader.Read(dst)
	fmt.Printf("n=%d data=%q err=%v\\n", n, dst[:n], err)
}

这里的关键观察是 Peek(4) 不会让后面的 Read 从第 5 个字节开始；Read 仍会从 0 开始取数据。但普通 Read 的返回值是 n 和 err，调用方必须使用 dst[:n]，不能无条件使用整个 dst。

构造真正的 ErrBufferFull：请求长度超过缓冲区

bufio.NewReaderSize 的缓冲区有最小容量，传入很小的值并不代表内部缓冲区真的只有几个字节。为了稳定复现 ErrBufferFull，直接请求一个明显超过默认缓冲区的 Peek 长度，并同时打印返回长度与错误：

package main

import (
	"bufio"
	"fmt"
	"strings"
)

func main() {
	// 使用默认缓冲区，故意请求远大于缓冲区的预览长度。
	reader := bufio.NewReader(strings.NewReader("abcdef"))
	data, err := reader.Peek(5000)

	// 只能把 data 当作当前可用前缀，不能当作 5000 字节完整结果。
	fmt.Printf("len=%d buffered=%d err=%v\\n", len(data), reader.Buffered(), err)
	if err == bufio.ErrBufferFull {
		// 这个分支说明请求超过了内部缓冲能力，不是 Peek 已经读完了目标数据。
		fmt.Println("Peek 请求超过缓冲区容量")
	}
}

如果业务目标是“判断前缀是否存在”，可以接受 Peek 的错误并改用流式扫描；如果业务目标是“拿到固定的 5000 个字节”，就不能靠更大的 Peek 绕过缓冲区，应改成分段读取或使用 io.ReadFull 配合可接受的目标长度。

另一个坑：Peek 返回的切片不能跨下一次读取

官方文档明确说明，Peek 返回的字节在下一次读操作后不再有效。它不是独立副本，而是 Reader 内部缓冲区的一段视图。因此，下面这种写法把生命周期拉长了：

// 预览结果只在下一次 Reader 读取前使用。
preview, err := reader.Peek(4)
if err != nil {
	return err
}

// 读取动作可能覆盖或移动内部缓冲区，旧 preview 不应再作为结果保存。
_, err = reader.ReadByte()
if err != nil {
	return err
}

// 正确做法是在跨越下一次读取前复制需要保留的数据。
saved := append([]byte(nil), preview...)

这里的“失效”不是说每次都一定能观察到乱码，而是调用方不能再依赖这段切片的内容。若预览结果要交给异步任务、缓存或后续函数保存，应该在下一次读操作前复制。

需要完整长度时，用 io.ReadFull 收口

若协议已经知道目标长度，例如固定头部、定长字段或已经解析出的消息体长度，使用 io.ReadFull 比手写一次 Read 更直接。它会持续读取，直到填满目标切片，或者遇到错误；输入提前结束时会返回已读字节数和 io.ErrUnexpectedEOF。

package main

import (
	"bufio"
	"fmt"
	"io"
	"strings"
)

func readMessage() error {
	// Peek 只用于判断前缀，不承担完整读取职责。
	reader := bufio.NewReader(strings.NewReader("MSG:hello"))
	prefix, err := reader.Peek(4)
	if err != nil {
		return fmt.Errorf("预览前缀失败: %w", err)
	}
	if string(prefix) != "MSG:" {
		return fmt.Errorf("未知消息前缀 %q", prefix)
	}

	// 目标长度确定后，用 ReadFull 处理底层 Reader 的多次短读。
	body := make([]byte, len("MSG:hello"))
	n, err := io.ReadFull(reader, body)
	if err != nil {
		// n 能帮助定位是输入不足还是读取中途失败。
		return fmt.Errorf("读取消息不完整: n=%d: %w", n, err)
	}
	fmt.Printf("完整消息=%q\\n", body)
	return nil
}

func main() {
	// 入口保留错误，便于把短读原因交给调用方。
	if err := readMessage(); err != nil {
		fmt.Println(err)
	}
}

注意，ReadFull 的目标切片应该是“确实需要的长度”。它不会凭空补齐数据：如果输入比目标短，仍然要处理 io.ErrUnexpectedEOF；如果输入本身可能无限等待，还要结合连接超时或取消机制。

按场景选择修复方式

回归检查清单：四个分支都要覆盖

修复后不需要依赖线上环境，写一个小型表驱动测试就能把边界固定下来。至少检查以下四类输入：

• 正常输入：Peek 成功，后续 ReadFull 得到完整目标。
• 短输入：Peek 或 ReadFull 返回短数据，并保留真实错误。
• 超大 Peek：返回 bufio.ErrBufferFull，业务不把前缀误判为完整结果。
• 切片生命周期：复制前缀后再读取，业务只使用复制结果。

排查时可以把日志字段固定为 peek_len、peek_err、read_n 和 read_err。这样看到“拿不到完整数据”时，先能回答是 Peek 请求超出缓冲区、输入提前结束，还是普通 Read 本来就只返回了一次短读。

常见问题

Peek 会不会把数据读走，导致后面的 Read 变少？

不会。Peek 不推进读取位置，后续 Read 仍可读取被预览的字节。真正需要注意的是 Peek 返回的切片只在下一次读操作前有效。

Read 返回的 n 小于切片长度是不是一定出错？

不一定。io.Reader 允许短读，调用方应先处理 n，再根据 err 决定是否继续；只有要求固定长度时，才应使用 io.ReadFull。

为什么 Peek 返回数据的同时还有错误？

当底层输入提前结束或请求超出缓冲区时，Peek 可能返回当前可用前缀和错误。前缀只能按“部分结果”处理，不能忽略错误后当成完整 n 字节。

复制 Peek 返回值是不是总会增加性能成本？

会有一次复制成本，但它换来了明确的生命周期。只要数据要跨越下一次读取、异步传递或长期保存，复制通常比持有内部缓冲区视图更可靠。