Go bufio.Reader预读协议头又保留正文的处理方案

网络协议或文件格式通常先放一个固定长度的头部，后面紧跟正文。想先判断魔数、版本或标志位，又不希望正文少掉几个字节时，直接对原始 io.Reader 调用 Read 很容易留下“读过但没放回去”的问题。更稳妥的做法是把它包成 bufio.Reader，用 Peek(n) 观察前 n 个字节，再继续使用同一个 Reader 读取正文。

先确定预读长度和读取边界

假设协议头是 8 字节：前 4 字节为魔数 GPK1，第 5 字节为版本，后 3 字节是标志位。创建 Reader 时不要只凭默认容量碰运气，至少给它能够容纳协议头的空间；若协议头长度可变，则把“最大头长度”作为明确的上限。

用 Peek 判断协议头，同时保留输入位置

关键点是判断和消费分离：Peek 只做协议识别，正文解析仍接收同一个 *bufio.Reader。下面的示例把协议头复制出来，避免后续读取覆盖底层缓冲区；复制不是为了“放回正文”，而是为了让日志或元数据在后续读取后仍然可靠。

package main

import (
	"bufio"
	"bytes"
	"fmt"
	"io"
)

func readPacket(src io.Reader) error {
	// 协议头固定 8 字节，缓冲区至少能容纳它
	br := bufio.NewReaderSize(src, 8)
	headerView, err := br.Peek(8)
	if err != nil {
		// 输入不足与缓冲区容量问题要原样区分
		return fmt.Errorf("peek header: %w", err)
	}
	header := append([]byte(nil), headerView...)
	if !bytes.Equal(header[:4], []byte("GPK1")) {
		return fmt.Errorf("unexpected magic %q", header[:4])
	}

	// Peek 没有推进位置，这次 ReadFull 仍会从协议头开始读
	fullHeader := make([]byte, 8)
	if _, err := io.ReadFull(br, fullHeader); err != nil {
		return fmt.Errorf("consume header: %w", err)
	}
	// 这里演示正文继续从同一个 Reader 读取，避免丢首字节
	body, err := io.ReadAll(br)
	if err != nil {
		return fmt.Errorf("read body: %w", err)
	}
	fmt.Printf("version=%d flags=%x body=%q\n", header[4], header[5:8], body)
	return nil
}

func main() {
	// 示例数据由 8 字节头部和正文拼成，不代表真实网络抓包
	_ = readPacket(bytes.NewReader([]byte("GPK1\x01\x00\x00\x07payload")))
}

这里有两种合法的正文策略：如果后续解析器需要先看到完整头部，就用 io.ReadFull(br, fullHeader) 消费 8 字节；如果头部只用于路由判断，也可以直接把 br 交给下一层，让它从头开始按协议读取。不要再次创建一个新的 Reader 去接同一个底层流，否则容易把已经缓冲的数据绕开。

复制 Peek 返回值并继续读取正文

官方文档特别提醒：Peek 返回的字节会在下一次读操作后失效。因此不能把 headerView 长期塞进异步任务、缓存或响应对象；需要保留时应使用 append([]byte(nil), headerView...) 或 bytes.Clone 创建独立副本。

正文长度固定时，用 io.ReadFull(br, body) 让“必须读满”成为代码契约；正文长度来自头部时，要先解析长度并设置上限，再分配或读取，避免恶意长度造成过大内存申请。正文是分隔格式时，ReadBytes 或 ReadString 比手写循环更直接，但末尾没有分隔符时要根据返回数据和错误共同判断。

ErrBufferFull、EOF 和短输入怎么处理

Peek 的 n 大于 Reader 缓冲区容量时会返回 bufio.ErrBufferFull；这不是“网络正文损坏”，而是预读策略超过了缓冲边界。可以在创建 Reader 时提高容量，也可以改成先读取一个固定的小前缀，再根据长度字段分阶段处理。不要无条件把所有错误都转成“协议头不匹配”，否则排查时会丢失真正原因。

落地前的四项检查

第一，确认协议头的最大长度没有超过 Reader.Size()；第二，确认 Peek 返回的切片不会跨越下一次读取继续使用；第三，确认判断、消费和正文解析共用同一个 Reader；第四，把短包、错误魔数和正文不完整分别记录。若协议头还没有固定长度，先设计小前缀和长度上限，再决定是否使用一次性 Peek。

常见问题

Peek 之后还需要调用 UnreadByte 吗？

不需要。Peek 本身不推进读取位置，而且官方文档明确说明它会影响紧接着的 UnreadByte 或 UnreadRune；预读协议头应继续使用同一个 Reader 读取。

Peek 返回的切片可以直接保存吗？

只能在下一次读操作前临时使用。要跨越后续读取保存协议头，复制成独立切片；不要把内部缓冲区的视图交给异步逻辑。

协议头比缓冲区大时能否自动扩大吗？

Peek 不会突破 Reader 的缓冲区上限，超出时返回 bufio.ErrBufferFull。提高 NewReaderSize 的容量，或把协议拆成固定前缀和受限变长部分。