Go bufio.Reader.Peek 怎样预览数据而不移动读取位置

如果你需要先检查输入的协议头、魔数或固定前缀，再决定后面怎么读，bufio.Reader.Peek(n) 是合适的入口。它返回接下来的最多 n 个字节，但不会前移 Reader 的读取位置；随后调用 Read 时，仍然会从这段数据开始读取。

要记住两个边界：Peek 返回的字节只保证在下一次读操作前有效；如果请求长度超过 Reader 的缓冲区容量，返回的错误会是 bufio.ErrBufferFull。官方地址：https://pkg.go.dev/bufio#Reader.Peek

把 Peek 当成“查看但不消费”，把 Read 当成“查看并消费”。判断只依赖前缀时可以 Peek；需要保存预览内容时，要在下一次读操作前复制。

Peek 解决的是哪一个问题

bufio.Reader 在底层 io.Reader 外面增加了一层缓冲。Peek(n) 会尽量让接下来的 n 个字节出现在缓冲区里，然后返回这段数据。它不会把读取游标向前移动，因此后续 Read 仍会读到相同的前缀。

这个语义适合“先判断、后选择”的场景。例如协议头的前 4 个字节决定后续解析器，文件头的固定标记决定编码处理方式，消息前缀决定是否交给某个解码分支。判断结束后，仍由普通读取操作消费数据。

用 Peek 预览固定前缀

下面的例子检查一个简单的消息前缀。比较时只读取预览内容，不在 Peek 后立即调用会改变缓冲状态的操作；确认类型后，再用 Read 消费真正的数据。

package main

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

func main() {
	// 预览协议前缀，Peek 不会让下一次 Read 跳过这 4 个字节。
	reader := bufio.NewReader(bytes.NewReader([]byte("GOv1:payload")))
	prefix, err := reader.Peek(4)
	if err != nil {
		// 前缀不完整时先结束判断，避免把短数据误当成合法消息。
		panic(fmt.Errorf("预览消息前缀失败: %w", err))
	}

	if !bytes.Equal(prefix, []byte("GOv1")) {
		// 不匹配时仍未消费输入，调用方可以选择另一种解析策略。
		fmt.Println("未知消息类型")
		return
	}

	consumed := make([]byte, 4)
	if _, err := reader.Read(consumed); err != nil {
		// Peek 后再 Read 才是真正消费前缀，读取错误不能被忽略。
		panic(fmt.Errorf("消费消息前缀失败: %w", err))
	}
	fmt.Printf("类型=%s，剩余缓冲=%d 字节\n", consumed, reader.Buffered())
}

这个流程的关键是顺序：先 Peek，完成判断，再 Read。若判断失败后还需要把前缀交给别的处理器，可以继续从同一个 Reader 读取；若要跳过它，则显式调用 Discard，不要把 Peek 当成消费动作。

n 不是“当前缓冲区已有多少”

传给 Peek 的 n 表示希望看到的字节数，不是当前缓存里已经存在的字节数。如果当前缓冲不足但 Reader 的容量允许，Peek 会尝试从底层输入继续填充；所以它可能触发底层读取，但仍不会前移逻辑上的读取位置。

如果只想知道当前缓冲区已经有多少可读字节，可以看 Buffered()。如果想预览一个完整的固定前缀，则直接请求前缀长度；不要先用 Buffered 判断“够不够”后就假设底层输入不会再有数据。

短读和 ErrBufferFull 怎样处理

Peek 返回的切片长度少于请求的 n 时，同时会返回解释原因的错误。可能是底层输入已经结束，也可能是发生了其他 I/O 错误；代码应当先检查错误和实际长度，不要只比较切片内容。

如果 n 大于 Reader 的缓冲区大小，官方文档规定错误为 ErrBufferFull。这不是“再等一次读取就能解决”的普通短读，而是请求超过了这个 Reader 能容纳的上限。需要更大的固定前缀时，应在创建 Reader 时使用足够大的 NewReaderSize，或者改用分段读取。

package main

import (
	"bufio"
	"bytes"
	"errors"
	"fmt"
)

func preview(reader *bufio.Reader, n int) ([]byte, error) {
	// n 必须是业务需要的前缀长度，而不是随意扩大到整条消息。
	data, err := reader.Peek(n)
	if err == nil {
		return data, nil
	}

	if errors.Is(err, bufio.ErrBufferFull) {
		// 请求超过缓冲容量时，调用方需要调整 Reader 大小或改成分段读取。
		return nil, fmt.Errorf("预览长度 %d 超过缓冲容量: %w", n, err)
	}
	// EOF 或底层 I/O 错误都保留，实际返回数据长度仍可用于诊断。
	return data, fmt.Errorf("预览数据不足，已得到 %d 字节: %w", len(data), err)
}

func main() {
	// 用小容量演示固定前缀必须与 Reader 容量匹配。
	reader := bufio.NewReaderSize(bytes.NewReader([]byte("0123456789")), 8)
	data, err := preview(reader, 4)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(data))
}

注意，Reader 的缓冲容量是上限约束，而不是建议把所有消息都一次性 Peek。对于长度不固定的内容，先 Peek 一个能判断类型的短前缀，确认后再按协议字段读取，通常更稳妥。

返回切片为什么不能跨越下一次读

Peek 返回的是 Reader 内部缓冲区的一段切片，不是自动复制出来的新数组。官方文档明确说明，下一次读操作后这段字节不再保证有效。因此，预览结果只用于立即判断时可以直接比较；需要放到结构体、异步任务或后续流程中时，应复制一份。

package main

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

func main() {
	// 预览结果只在下一次读之前安全；需要长期保存时立即复制。
	reader := bufio.NewReader(bytes.NewReader([]byte("HEADbody")))
	view, err := reader.Peek(4)
	if err != nil {
		panic(err)
	}

	saved := append([]byte(nil), view...)
	// 复制后再读取，saved 不依赖 Reader 内部缓冲区的生命周期。
	_, _ = reader.Discard(4)
	fmt.Printf("预览=%s，保存=%s\n", view, saved)
}

如果只是判断前缀，可以把 bytes.Equal 或逐字节比较放在下一次 Read 之前完成。如果要把结果保存下来，append([]byte(nil), view...) 是一个直观的浅层内容复制方式；也可以用 bytes.Clone 表达同样的意图。

Peek、Read 和 Discard 如何组合

一个清楚的读取流程通常只有三个动作：

1. 用 Peek 查看足以决定分支的最短前缀。
2. 用 Read 或协议解析函数消费需要保留的内容。
3. 对明确不需要的数据调用 Discard，并检查它返回的实际跳过数量和错误。

不要用 Peek 代替 Read 来做循环消费，也不要在 Peek 得到切片后跨越多个读操作才使用它。把“判断”和“消费”分开，既能避免读取位置错乱，也能让错误归因更直接。

常见问题

Peek 会不会从底层 io.Reader 读取数据？

会。为了让请求长度可用，Peek 必要时会填充缓冲区；但它不会推进 bufio.Reader 的读取位置。

Peek(0) 会消费数据吗？

它不用于消费数据。若业务要判断输入是否有内容，应根据协议设计明确的读取策略，不要把零长度预览当成可靠的 EOF 探测。

为什么 Peek 后 UnreadByte 可能失败？

Peek 会影响 Reader 对最近操作的记录，官方文档规定，在下一次读操作前调用 UnreadByte 或 UnreadRune 可能不成功。需要回退时，应围绕实际 Read 设计读取流程。

Peek 返回的数据可以直接保存吗？

不建议。它指向内部缓冲区，下一次读操作后有效性不再保证；需要保存时立即复制。

小结

bufio.Reader.Peek(n) 的核心价值是“预览而不消费”：它可以触发底层填充，但不移动读取位置。实际使用时先请求足够短的判断前缀，检查返回长度和错误；ErrBufferFull 表示请求超过 Reader 容量；返回切片只在下一次读前有效，需长期保存就及时复制。把 Peek、Read、Discard 分别当作查看、消费、跳过，读取流程会更容易维护。