当前位置：首页 > 文章列表 > Golang > Go问答 > Go bufio.Reader 的 Peek 为什么不移动游标：Peek、Discard 与协议解析边界

Go bufio.Reader 的 Peek 为什么不移动游标：Peek、Discard 与协议解析边界

来源：17golang原创 2026-07-23 22:35:44 0浏览收藏

写 TCP 私有协议时，常见的帧格式是「固定长度头部 + 变长正文」：头部里先放 4 字节长度，正文再按长度读取。代码一旦把 bufio.Reader.Peek 当成“读取”操作，就会出现长度判断重复、帧头被意外跳过，甚至下一个请求整体解析错位的问题。核心边界规则很清晰：Peek 只查看缓冲区数据但不会移动游标，真正要消费已确认合法的数据，得用 Read、ReadFull 或者 Discard 完成。

要点速览

Peek(n) 返回缓冲区前 n 个字节的视图，完全不会让 Reader 的游标前进。
确认帧头内容合法之后，用 Discard 直接消费掉头部，也可以直接用 ReadFull 把头部内容读到独立的数组里存起来。
网络流可能只传过来半个帧头，遇到 bufio.ErrBufferFull 或者数据暂时不完整的情况，不能直接把半包当成非法坏包处理。
UnreadByte 只适合撤回最近一次成功读取的单个字节，完全不能替代协议层的回滚逻辑。

Go bufio.Reader Peek 查看协议帧头但不消费，确认长度后用 Discard 推进游标的工程证据图

先把 bufio.Reader 的游标逻辑理清楚

bufio.Reader 只是在外层包裹了一层输入流，内部维护了一段已经读到内存里的缓冲区。业务代码实际接触到两个状态：底层连接当前能继续读到的位置，以及缓冲区里还没交给业务逻辑处理的字节范围。Peek 只是返回这段未处理内容的切片视图，根本不会把这些字节标记成“已处理”。

下面的小例子可以直接验证两者的差异：

r := bufio.NewReader(strings.NewReader("ABCD"))

head, err := r.Peek(2)
fmt.Printf("peek=%q err=%v\n", head, err)

first, err := r.ReadByte()
fmt.Printf("read=%q err=%v\n", first, err)

rest, err := r.Peek(2)
fmt.Printf("peek-again=%q err=%v\n", rest, err)

输出里的两次预览动作，都会从当前游标位置开始读。第一次 Peek(2) 拿到的是 AB 的内容，真正调用 ReadByte 之后，游标才会越过 A 的位置，第二次预览拿到的就只有 BC 了。这里要注意别把 Peek 返回的切片长期存着，它直接指向 Reader 的内部缓冲，后续的读取操作很可能把这块内容覆盖掉，拿到的数据就不对了。

用 Peek 预览长度后，消费动作要紧跟在校验逻辑后面

假设我们的协议头部是 4 字节大端整数，专门用来标记后续正文的长度。解析流程可以先预览头部内容，先判断长度有没有超过 1 MiB 的安全阈值，确认字段合法之后，用 Discard 直接消费掉头部，最后再调用 io.ReadFull 读完整段正文。

const maxPayload = 1  maxPayload {
		return nil, fmt.Errorf("payload too large: %d", payloadSize)
	}

	if _, err := r.Discard(4); err != nil {
		return nil, err
	}

	payload := make([]byte, payloadSize)
	if _, err := io.ReadFull(r, payload); err != nil {
		return nil, err
	}
	return payload, nil
}

这段代码把数据处理拆成了三个清晰的阶段：先只从缓冲区观察头部内容，校验长度规则，确认没问题之后才移动游标拉取正文。如果长度超出阈值就直接退出，不调用 Discard，连接上的原始字节会完整保留下来，调用方可以自行决定记录协议错误、关闭连接，或是把异常交给上层逻辑处理。

动作	是否移动游标	适合放在协议解析的哪一步
`Peek(n)`	否	预览魔数、版本号、长度字段
`Read`/`ReadByte`	是	消费已经确认合法的字段
`Discard(n)`	是	丢弃不需要保留内容的头部或者分隔符
`ReadFull`	是	必须完整拿到的固定长度正文

半包到达时先等待数据补全，不要误判为坏包

TCP 本身是没有消息边界的。发送端一次写入 20 字节，接收端完全可能先拿到 2 字节，后续再拿到剩下的 18 字节。第一次调用 Peek(4) 如果缓冲区里只有 2 字节，返回的不是半截可以用来解析的头部，而是对应错误。处理逻辑要区分三种状态：输入流已经结束、本地缓冲区容量不足、协议字段确实非法。

如果协议头部长度已经超过 Reader 默认的缓冲容量，Peek 就会返回 bufio.ErrBufferFull。这不是远端传来了坏数据，只是本地缓冲区放不下你要求预览的字节数。协议头部本身应该设计得尽量小且固定，如果确实需要查看较长的字段，要么提前调高 Reader 的初始化容量，要么改用分段读取的方式，不要无限制扩大内存占用。

func waitHeader(r *bufio.Reader) ([]byte, error) {
	header, err := r.Peek(4)
	if err == nil {
		return header, nil
	}
	if errors.Is(err, bufio.ErrBufferFull) {
		return nil, fmt.Errorf("reader buffer cannot hold frame header: %w", err)
	}
	return nil, err
}

真实网络读取场景里，短暂的“数据还没到齐”基本都能靠下一轮读取自然补全，但如果底层连接已经返回 io.EOF，说明对端在帧头还没收完的时候就提前关闭了连接，这种情况才应该记录成截断帧。判断的核心依据是流的终止状态，不能只靠“本轮 Peek 没拿到完整字段”这一个条件就下结论。

Go bufio.Reader 半包协议帧从两字节头部到完整帧的状态变化，校验失败时停止消费

UnreadByte 只能回退单步，不能用来让协议解析任意回滚

UnreadByte 的能力范围非常窄：它只能撤回最近一次成功读取的单个字节，而且两次调用之间不能插入其他读取操作。下面这种场景用它就很合理：先读一个分隔符，发现这个字节其实属于下一个字段，就把这一个字节还回缓冲区就行。

b, err := r.ReadByte()
if err != nil {
	return err
}
if b != ':' {
	if err := r.UnreadByte(); err != nil {
		return err
	}
	return readNextField(r)
}

但它完全支持不了“读了 12 字节发现之前的判断错了，想全部退回去”这类需求。协议解析如果需要做多字节试探，优先用 Peek 做预览，如果已经确认要消费内容，直接把字段读到自己创建的切片里，解析失败的时候直接关闭当前帧或者连接就好。别把业务状态和 Reader 的内部位置强行绑定，后期很难确认每条错误分支都没有出现漏跳字节的问题。

用测试覆盖长度边界、半包场景和错误消费逻辑

这类问题最值得写测试用例的地方反而不是正常帧的流程，而是“数据刚好卡在边界点”的异常场景。测试可以用 strings.NewReader 或者自定义 Reader 模拟输入，完全不需要启动真实的 TCP 服务。

func TestReadFrame(t *testing.T) {
	payload := []byte("hello")
	frame := make([]byte, 4+len(payload))
	binary.BigEndian.PutUint32(frame[:4], uint32(len(payload)))
	copy(frame[4:], payload)

	got, err := readFrame(bufio.NewReader(bytes.NewReader(frame)))
	if err != nil {
		t.Fatal(err)
	}
	if string(got) != "hello" {
		t.Fatalf("payload=%q", got)
	}
}

正文长度为 0：确认空正文属于合法帧还是需要直接拒绝。
只返回 2 个头部字节：确认连接提前结束时能正确返回截断错误。
长度超过 maxPayload：确认游标没有被 Discard 提前推进。
两个完整帧连续拼接：确认第一帧消费完成后，第二帧的解析仍然从正确的位置开始。

把协议解析拆成「观察、校验、消费」三步

bufio.Reader 的坑从来不是 API 难用，而是很多人把观察逻辑和消费逻辑混在了一起。先用 Peek 拿到不会推进游标的视图，先校验魔数、版本号和长度规则；确认字段全部合法之后，才用 Discard、Read 或者 ReadFull 推进游标。把半包等待、缓冲上限、提前 EOF 和各类错误路径都补上测试，解析器的游标状态就能一直保持清晰可查。