Go 1.26 bytes.Buffer.Peek 怎么迁移：非消费式预览、EOF 与兼容边界

解析 TCP 长度前缀、二进制协议头或消息队列帧时，经常要先看一眼前几个字节，再决定后面怎么读。以前用 bytes.Buffer.Next，预览动作会顺手推进读取位置；Go 1.26 的 bytes.Buffer.Peek 把“只看不取”变成了标准库方法。

先看 Next 和 Peek 的读取位置差异

假设缓冲区里有一个两字节版本号，后面紧跟正文。Next(2) 会把这两个字节消费掉；Peek(2) 只返回视图，下一次读取仍然从原位置开始。

var buf bytes.Buffer
buf.WriteString("v1|payload")

header, err := buf.Peek(2)
fmt.Printf("header=%q err=%v len=%d\n", header, err, buf.Len())

body, _ := io.ReadAll(&buf)
fmt.Printf("body=%q\n", body)

这段代码的关键不是少写一行，而是把“判断协议头”和“推进消费位置”拆开。协议头不匹配时，可以直接拒绝；匹配时，再用正常读取继续处理完整消息。

参数不足时，部分结果和 io.EOF 要一起处理

Peek(n) 不会为了凑够 n 个字节而等待。当前只有 3 个字节、调用 Peek(8) 时，它会返回这 3 个字节并同时返回 io.EOF。这很适合做“当前缓冲区是否已经有完整帧”的判断：

head, err := buf.Peek(8)
if err != nil {
	if errors.Is(err, io.EOF) {
		// 先保留现场，等待下一批网络数据
		return nil
	}
	return err
}
if !bytes.Equal(head[:2], []byte{'v', '1'}) {
	return fmt.Errorf("unsupported frame")
}

这里不能只写 if len(head) == 0。部分数据同样意味着帧尚未完整，应该回到接收循环，而不是把半个头交给解码器。

返回切片不能跨过下一次写入保存

Peek 返回的切片指向 Buffer 的内部存储。文档明确说明，下一次对缓冲区进行读写后，这个切片就不再适合继续使用。需要把头部交给异步任务、缓存到结构体或跨函数保存时，先复制一份：

preview, err := buf.Peek(4)
if err != nil && !errors.Is(err, io.EOF) {
	return err
}
headerCopy := bytes.Clone(preview)

// 后续可以继续写 buf；headerCopy 不再依赖 buf 的内部数组
buf.WriteString("more")
useLater(headerCopy)

短生命周期的同步判断可以直接用返回值；跨越下一次 Read、Write、Reset 或 Truncate，就按“借用视图”处理。这个边界比是否发生了内存分配更重要。

旧工具链用适配函数隔离升级影响

Peek 是 Go 1.26 新增的方法。公共库如果仍需被 Go 1.25 或更早版本编译，不能在共享源码里直接引用它。更稳妥的迁移方式是先抽出一个“预览头部”接口，再分别提供新旧实现。

兼容实现要格外小心：用 Next 取出内容后再把读取位置恢复，通常比直接使用 Peek 更容易引入并发或失败路径问题。若兼容层无法证明恢复动作安全，宁可继续复制一个短前缀并让上层明确承担读取位置变化。

四类测试能把迁移边界锁住

func TestPeekContract(t *testing.T) {
	cases := []struct {
		name string
		data string
		n    int
		want string
		err  error
	}{
		{"full", "v1|data", 2, "v1", nil},
		{"partial", "v", 2, "v", io.EOF},
		{"empty", "", 2, "", io.EOF},
	}
	for _, tc := range cases {
		t.Run(tc.name, func(t *testing.T) {
			var buf bytes.Buffer
			buf.WriteString(tc.data)
			got, err := buf.Peek(tc.n)
			if string(got) != tc.want || !errors.Is(err, tc.err) {
				t.Fatalf("got %q, %v", got, err)
			}
			if tc.name == "full" && buf.Len() != len(tc.data) {
				t.Fatal("Peek advanced the buffer")
			}
		})
	}
}

除了完整、部分和空缓冲区，还要补一条“返回切片在下一次写入后不再使用”的约定测试。测试不必依赖具体底层数组地址，只需保证业务代码在跨越缓冲区修改时使用了复制结果。

迁移前后的短清单

1. 把所有“先看头部再决定读取”的代码找出来，确认原实现是否意外推进了位置。
2. 明确部分数据时的返回策略：等待更多输入、拒绝帧，还是按协议返回错误。
3. 凡是跨越下一次缓冲区修改保存的切片，改成 bytes.Clone 或显式复制。
4. 检查 go.mod、CI 镜像和发布构建机是否都已达到 Go 1.26。
5. 用 Go 1.26 与旧兼容工具链各跑一次测试，避免迁移只在本地成立。

相关问题

Peek 会改变 Buffer.Len 吗？

不会。它只返回当前位置开始的切片，成功或返回 io.EOF 都不会消费数据。

Peek 返回部分数据时能直接解析吗？

通常不能。若协议要求固定长度，应先处理 io.EOF，等待数据补齐后再解析。

Peek 返回的切片能保存到结构体吗？

不建议跨越下一次缓冲区读写保存。需要长期持有时复制到独立切片。

Go 1.25 能直接使用 bytes.Buffer.Peek 吗？

不能。应继续使用兼容实现，或先把项目最低工具链升级到 Go 1.26。

bytes.Buffer.Peek 解决的是一个很具体的读取语义：先观察，不推进。迁移时真正要守住的是三件事——部分数据如何处理、返回切片何时失效、最低 Go 版本是否一致。把这三点写进测试，API 替换才不会只停留在编译通过。