Go bufio.Reader Peek 预读协议头的参数边界

在自定义 TCP 协议、网关探测或多协议复用里，我们常常需要“先看一眼协议头，再决定交给哪个解析器”。我更倾向于用 bufio.Reader.Peek 做这件事：它能返回接下来的若干字节，却不会推进读取位置。不过，Peek 好用的前提是把三个边界想清楚：参数 n 不能随意增长、返回切片不是永久数据、等待协议头也必须受连接超时约束。

本文用一个固定 8 字节协议头说明：前 2 字节是 magic，第 3 字节是版本，第 4 字节是标志位，最后 4 字节是大端序消息体长度。结论先给出：固定头长度必须小于等于 Reader 的缓冲区容量；校验必须在下一次读取前完成；需要长期保存时必须复制；验证通过后再 Discard 头部并读取受限长度的消息体。

Peek 的三条参数边界

官方文档对 Peek 的语义很明确：它返回接下来的 n 个字节且不推进读取位置；为凑够 n 个字节，它可能继续从底层 Reader 读取；返回切片只在下一次读操作之前有效。如果可返回字节少于 n，错误会解释原因。特别地，n 大于内部缓冲区容量时会返回 bufio.ErrBufferFull。

图1：Peek 的参数不是“想看多少就看多少”，它同时受 Reader.Size() 与借用切片生命周期约束。

我第一次使用 Peek 时最容易误会的是：既然底层连接里可能还有更多数据，缓冲区不够时 Reader 是否会自动扩容？答案是否定的。bufio.Reader 的缓冲区大小在创建时就确定了，Peek 不会为了一个更大的 n 改变容量。因此协议头是固定 8 字节时，最好把 8 写成协议常量，并在构造 Reader 时明确给出足够容量。

const headerLen = 8

func newProtocolReader(conn net.Conn) *bufio.Reader {
    // 显式给出容量，保证固定协议头能够完整预读
    return bufio.NewReaderSize(conn, 4096)
}

func peekHeader(r *bufio.Reader) ([]byte, error) {
    // 配置错误应尽早暴露，不能把它当成普通网络短读
    if headerLen > r.Size() {
        return nil, fmt.Errorf("协议头长度 %d 超过缓冲区 %d", headerLen, r.Size())
    }

    header, err := r.Peek(headerLen)
    if err != nil {
        // ErrBufferFull 表示请求参数与缓冲区配置不匹配
        if errors.Is(err, bufio.ErrBufferFull) {
            return nil, fmt.Errorf("预读参数越界: %w", err)
        }
        // EOF 或其他读取错误表示协议头没有完整到达
        return nil, fmt.Errorf("协议头不完整，已获得 %d 字节: %w", len(header), err)
    }
    return header, nil
}

源码里还有两个值得记住的细节。第一，负数 n 会返回 bufio.ErrNegativeCount；第二，调用 Peek 后，直到下一次读操作之前，UnreadByte 和 UnreadRune 都不会成功。协议解析器不应同时依赖 Peek 和“撤销读取”语义，否则状态很难推断。

返回值是借用切片，不是协议头副本

Peek 返回的切片直接引用 Reader 的内部缓冲区。只要调用了下一次读操作，包括 Read、ReadByte、Discard 或另一次可能填充缓冲区的 Peek，先前切片的内容就不再有稳定性保证。因此应在借用期内完成 magic、版本、标志和长度字段解析。

如果协议头要放进异步任务、日志队列或另一个 goroutine，就先复制。不要只复制切片头；应复制底层字节：

header, err := r.Peek(headerLen)
if err != nil {
    return err
}

// 需要跨越下一次读取保存时，复制底层字节
savedHeader := append([]byte(nil), header...)
_ = savedHeader

反过来，如果解析结果只是当前函数里的几个整数，就没有必要复制。直接从借用切片解析完字段，然后在校验通过后消费头部，内存行为更简单。

把预读结果放进协议安全边界

协议头来自网络，不能因为已经凑够 8 字节就默认可信。真正需要保护的是连接槽位、内存预算和下游解析器。攻击者可以只发送半个头部拖住连接，也可以把 bodyLen 写成极大值诱导服务端分配内存，还可以构造未知版本触发错误分支。

图2：Peek 只负责把固定头部呈现给解析器，截止时间、字段校验和消息体上限共同构成安全边界。

下面的示例先设置读截止时间，再预读和校验头部。只有全部字段通过检查，才调用 Discard(8) 消费协议头。随后使用 io.ReadFull 读取已经过上限校验的消息体。

var (
    errBadMagic   = errors.New("非法协议标识")
    errBadVersion = errors.New("不支持的协议版本")
)

const (
    headerLen  = 8
    maxBodyLen = 1  maxBodyLen {
        return Frame{}, fmt.Errorf("消息体长度 %d 超过上限 %d", bodyLen, maxBodyLen)
    }

    version, flags := header[2], header[3]
    // 校验通过后才推进读取位置，消费固定长度协议头
    if _, err := r.Discard(headerLen); err != nil {
        return Frame{}, fmt.Errorf("消费协议头失败: %w", err)
    }

    // 只按已校验的长度分配内存并完整读取消息体
    body := make([]byte, int(bodyLen))
    if _, err := io.ReadFull(r, body); err != nil {
        return Frame{}, fmt.Errorf("读取消息体失败: %w", err)
    }
    return Frame{Version: version, Flags: flags, Body: body}, nil
}

Discard 很适合表达“我已经检查过这些字节，现在正式消费它们”。当要丢弃的数量不超过 Buffered() 时，它不会再次读取底层 Reader。这里 8 字节刚由 Peek 成功返回，因此 Discard 可以精确推进到消息体起点。

错误分类比统一重试更重要

生产代码里，我不会把 Peek 的所有错误都放进同一个重试循环。ErrBufferFull 通常是本地参数或容量配置错误，重试不会让缓冲区变大；EOF 且长度不足说明对端发送了截断帧；超时说明连接没有在预算内交付完整头部；magic 或版本错误则属于协议拒绝。分类后记录必要上下文并关闭或回收连接，比无条件继续等更可控。

还要避免把网络分片误认为协议错误。TCP 不保证一次底层 Read 就得到完整 8 字节，但 Peek 会尝试继续填充缓冲区，直到凑够 n、遇到错误或达到缓冲区边界。因此“只收到 3 字节”本身不是失败；在截止时间前继续到达的数据仍能组成完整头部。

什么时候不该用 Peek

如果协议头本来就会立即被消费，而且无需根据头部选择不同解析路径，直接用 io.ReadFull 读入一个独立数组通常更直观。Peek 更适合“查看后再决定”的场景，例如区分 TLS 与明文协议、识别多个自定义魔数，或在不破坏输入的前提下让路由层做判断。

另一个边界是可变超长头部。不要根据网络输入直接执行 Peek(int(length))。应先预读固定前缀，从前缀中解析长度并校验上限，然后选择受限读取或分段解析。只要 n 可能超过 Reader.Size()，就必须先有明确的容量策略。

常见问题

Peek 成功后 Buffered() 会减少吗？

不会。Peek 不推进读取位置，数据仍然处于缓冲区中。只有 Read、Discard 等消费操作才会改变后续读取位置。

ErrBufferFull 是否表示网络数据太大？

不一定。在 Peek 场景里，它首先表示请求的 n 超过 Reader 可提供的缓冲区边界，常见原因是协议头常量与 NewReaderSize 配置不一致。消息体是否过大应由协议字段上限单独判断。

可以把 Peek 返回的切片传给 goroutine 吗？

不建议直接传。其他代码一旦继续读取同一个 Reader，切片就可能失效。需要跨读取周期或跨 goroutine 保存时，先复制字节，并另外处理并发访问 Reader 的同步问题。

为什么还要设置 SetReadDeadline？

Peek 可能为了凑够 n 从底层连接继续读取。没有截止时间时，慢速或恶意客户端可以长时间只发送部分头部。net.Conn.SetReadDeadline 能把等待约束到连接资源预算内。

官方资料

可以对照 Go 官方文档与源码确认边界：https://pkg.go.dev/bufio、https://go.dev/src/bufio/bufio.go，连接截止时间语义见 https://pkg.go.dev/net。

把 Peek 理解成“有容量上限的短期借阅”就不容易出错：n 由固定协议定义并受 Reader.Size() 限制，借用切片在下一次读取前完成解析，不可信长度先校验再分配，等待过程由 deadline 兜底。这样，预读协议头才是一个清晰的解析边界，而不是隐藏状态的来源。