Go bufio Peek 请求长度超过缓冲区时怎么处理

bufio.Reader.Peek(n) 只查看接下来的字节，不推进读取位置；但它不能把缓冲区变成任意长度的临时缓存。请求长度超过该 Reader 的实际缓冲区容量时，返回当前可用字节并同时返回 bufio.ErrBufferFull。处理这类问题的关键，是先区分“请求超过容量”和“底层输入本身还没有这么多数据”。

官方接口地址：https://pkg.go.dev/bufio@go1.27.3#Reader.Peek。下面只围绕 Reader.Size、Peek 的返回值和错误模型展开，不把 Peek 当成通用的大块读取接口。

先看清 Peek 返回的三部分

一次调用要同时看三个结果：返回切片、错误值和调用前后读取位置的语义。切片表示当前能提供的预读字节；成功时长度应等于请求的 n；出错时也可能包含一部分数据。Peek 不消费这些字节，不过返回的切片只保证在下一次读操作前有效，所以不要把它长期保存后再当作独立缓存使用。

Reader.Size() 返回底层缓冲区的实际大小。它不是本次调用中已经缓存的字节数；已经缓存多少要看 Buffered()。如果通过 NewReaderSize 请求的大小小于实现允许的最小缓冲区，实际大小还可能高于传入值，因此排查时优先记录 Size() 的结果。

Peek 的上限不是请求长度

当 n > Reader.Size() 时，Peek 不会为了满足本次请求自动扩大缓冲区。源码会返回当前缓冲区中的字节，并给出 bufio.ErrBufferFull。因此，下面这种写法不能把“想看 8 KB”变成“Reader 一定能预读 8 KB”。

package main

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

func main() {
    reader := bufio.NewReaderSize(bytes.NewReader([]byte("header-payload")), 8)

    // Peek 只查看数据，不推进 Reader；n 超过实际容量时不能自动扩容。
    preview, err := reader.Peek(12)
    fmt.Printf("size=%d buffered=%d bytes=%q err=%v\n",
        reader.Size(), reader.Buffered(), preview, err)
}

这段代码的重点不是某一行输出，而是返回契约：preview 可能只有缓冲区能容纳的那部分内容，err 是 bufio.ErrBufferFull。如果调用方只判断 len(preview)，就可能把短切片误认为完整头部；如果只判断错误、不看切片，又可能丢掉已经预读的数据。

另一个容易混淆的量是 Buffered()。它表示当前还没有被消费的字节数，可能小于 Size()。即使 n 没有超过容量，底层 Reader 也可能只提供了较短输入，最终返回部分切片和底层错误。

把三个错误分开处理

Peek 的错误值对应不同的调用方动作：负数是参数错误；超过容量是预读策略不适配；容量以内但输入不足，则应根据底层错误决定是等待、重试还是结束。不要用“只要不是 nil 就重新创建 Reader”这种统一处理覆盖三种情况。

如果 n 恰好不超过容量，但底层数据在填充过程中提前结束，错误不一定是 ErrBufferFull，而可能是底层 Reader 返回的 io.EOF 或其他错误。错误值说明的是“为什么没有凑够 n 个字节”，不能只看返回切片的长度来猜原因。

先 Peek 固定长度头部，再读取完整内容

Peek 更适合检查固定长度、而且不应被消费的头部，例如先确认协议标记，再根据头部声明的长度读取后续内容。头部长度必须不超过 Reader 的实际容量；如果协议允许头部大于容量，就不应把“完整头部”设计成一次 Peek 请求。

package frame

import (
    "bufio"
    "encoding/binary"
    "fmt"
    "io"
)

const headerSize = 4

// ReadPayload 先检查固定头部，再按头部长度读取正文；调用方负责处理返回错误。
func ReadPayload(r *bufio.Reader) ([]byte, error) {
    if r == nil {
        return nil, fmt.Errorf("读取器不能为空")
    }
    if r.Size() 

这里的边界是有意限定的：Peek 只负责验证固定头部，真正消费数据由 io.ReadFull 完成。头部里的长度来自输入，因此示例仍然需要在真实协议中增加最大帧长、整数范围和业务配额限制；不能因为头部能 Peek 就默认正文一定安全或一定完整。

如果头部本身可能很长，应该重新设计解析契约：先按小块读取并逐步识别边界，或者让协议提供固定大小的长度字段。把 Reader 缓冲区盲目调到一个很大的值，只是把内存约束推迟，并没有解决输入长度不可控的问题。

调整缓冲区时看实际容量

当业务明确需要预读一段固定大小的数据，可以在创建 Reader 时给出足够的容量，并在配置层记录这个决定。不要在调用 Peek 失败后反复调用 Peek；失败不会让同一个 Reader 的缓冲区自动变大。

// NewPeekReader 创建一个用于固定头部预览的 Reader。
func NewPeekReader(src io.Reader, capacity int) (*bufio.Reader, error) {
    if src == nil {
        return nil, fmt.Errorf("输入源不能为空")
    }
    if capacity 

如果传入的 src 本身已经是一个容量更大的 *bufio.Reader，NewReaderSize 可能直接复用它；所以兼容封装应该以返回的 Reader 为准，用 Size() 做决策。这里的“增大容量”发生在创建阶段，不是 Peek 的补救动作。

排查 Peek 短返回时的速查表

这四项足够覆盖标题中的大多数问题。不要把“缓冲区容量不足”“输入源已经结束”“参数为负”混成同一条重试策略，也不要把返回了一部分字节写成“Peek 读取成功”。在协议解析里，长度、错误和消费时机必须各自有清晰的责任。

几个常见疑问

Peek 会不会推进读取位置？

不会。它只查看接下来的字节；但返回切片在下一次读操作后不再保证有效。如果需要长期保存，应复制到自己的切片。

为什么 n 小于缓冲区大小仍然会返回 io.EOF？

因为容量只是 Reader 能容纳的上限，底层输入可能先结束。此时 n 没有超过容量，但输入没有足够字节，错误就反映底层结束原因。

遇到 ErrBufferFull，继续 Peek 能解决吗？

不能。对同一个 Reader 重复请求同样长度不会改变容量。应在创建阶段调整容量，或把预览任务改成固定的小头部检查与后续完整读取。

Buffered 和 Size 应该看哪个？

判断上限看 Size()，判断当前已经预读多少看 Buffered()。两者回答不同问题，不能互相替代。

最后记住：Peek 解决的是“暂时查看而不消费”，不是“保证任意长度都能一次拿到”。先用 Size() 约束请求，再按错误值处理短返回，才能让缓冲区边界和协议读取行为保持一致。