bufio.Reader 怎么安全读取带前缀长度的二进制帧

读取“长度前缀 + payload”的二进制帧时，最容易出现的误判是：调用一次 bufio.Reader.Read，看到返回值不为空，就把它当成完整帧。实际上，Reader 的一次读取可能少于目标切片长度。稳妥的做法是先用 io.ReadFull 读满固定长度的帧头，再按协议约定解析长度，检查上限后分配 payload，最后再次用 io.ReadFull 读满正文。

官方文档：https://pkg.go.dev/bufio　https://pkg.go.dev/io#ReadFull　https://pkg.go.dev/encoding/binary#ByteOrder

安全边界只有一个顺序：长度字段先读满，解析后先限额，payload 再读满。只要 n != len(buf) 或 err != nil，就不能把这次读取当成完整帧。

问题现场：一次 Read 为什么不等于一帧

假设帧格式固定为 4 字节大端序长度字段，后面紧跟指定数量的 payload：

+----------------------+------------------------+
| 4 bytes, big-endian  | payload, length bytes  |
+----------------------+------------------------+

如果直接把 payload 缓冲区传给 Read，返回的 n 可能小于 len(payload)。这不一定是连接断开，也不一定是协议错误，它只表示这次调用拿到了当前可用的一部分数据。帧读取器必须继续读，直到目标缓冲区填满或明确遇到错误。

长度字段不能直接信任

长度字段是后续内存分配的输入，应该先固定读取 4 字节，再按约定字节序解释。解析结果在分配之前必须经过最大长度检查，否则一个异常的大数字就可能让程序申请不必要的内存。

package frame

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

const maxFrameSize = 1  uint64(maxFrameSize) {
        return 0, fmt.Errorf("payload 长度 %d 超过上限 %d", length, maxFrameSize)
    }

    // 通过上限检查后再转为 int，避免在分配前留下溢出或超大申请空间。
    return int(length), nil
}

这里把长度比较写成 uint64(length) > uint64(maxFrameSize)，是为了让“协议字段”和“本机分配参数”在转换前保持清晰的边界。长度超过上限时，读取器可以返回错误；不要先 make 再判断。

payload 读取要看 n 和 err

拿到合法长度后，再创建刚好对应的缓冲区。io.ReadFull 会持续读取，直到缓冲区填满或读取过程报错。完整读取时 n == len(payload) 且 err == nil；如果只收到一部分就结束，常见结果是 io.ErrUnexpectedEOF。

package frame

import (
    "bufio"
    "errors"
    "fmt"
    "io"
)

func readFrame(r *bufio.Reader) ([]byte, error) {
    length, err := readFrameHeader(r)
    if err != nil {
        return nil, err
    }

    payload := make([]byte, length)

    // ReadFull 负责补齐短读；返回成功时，payload 才能被当作完整帧正文。
    n, err := io.ReadFull(r, payload)
    if err == nil {
        return payload, nil
    }

    // 头后只收到部分正文，属于截断帧，不要把半个 payload 交给上层。
    if errors.Is(err, io.ErrUnexpectedEOF) {
        return nil, fmt.Errorf("帧正文被截断: 已读 %d/%d 字节: %w", n, length, err)
    }

    // 其他错误保留底层原因，便于调用方区分连接关闭和设备/文件错误。
    return nil, fmt.Errorf("读取帧正文失败: 已读 %d/%d 字节: %w", n, length, err)
}

注意，io.EOF 与 io.ErrUnexpectedEOF 的含义不同：读取一个非空 payload 时，如果一个字节都没有读到就结束，可能得到 io.EOF；已经读到部分但没有填满，通常得到 io.ErrUnexpectedEOF。调用方不应只判断 n > 0，而应该优先判断错误。

把异常长度挡在内存分配之前

长度校验至少要覆盖三个边界：

• 零长度：是否允许空 payload，要由帧格式决定；如果不允许，应在解析后明确拒绝。
• 最大长度：超过应用允许的上限时直接返回错误，不能为了“读完”而不断扩容。
• 类型转换：先与上限比较，再转成 int 并创建切片。

这个上限是读取器的资源边界，不是网络协议设计。它只回答一个工程问题：当前组件愿意为单帧 payload 分配多少内存。上层如果要处理更大的内容，应采用明确的分片或流式方案，而不是让这个函数无限制地接受长度字段。

用四类输入复查读取结果

不运行正文代码也可以先把复查矩阵写清楚，后续接入真实 Reader 时按同样的边界覆盖：

常见误区与结论

误区一：把一次 Read 当成完整帧。修正方式是对固定长度的帧头和正文都使用 io.ReadFull。

误区二：先按长度分配，再检查长度。修正方式是先解析、先限额，最后才转换类型和创建 payload。

误区三：看到 n 大于 0 就继续处理。修正方式是同时检查 n 和 err，截断帧不能交给上层当完整帧使用。

最终可以把读取逻辑压缩成一句话：bufio.Reader 负责提供带缓冲的读取入口，io.ReadFull 负责填满目标切片，binary.BigEndian 负责解释长度字段，而最大长度检查负责把不可信输入挡在内存分配之前。

相关问题

• 为什么不用 Scanner 读取二进制帧？Scanner 面向 token，不适合由固定字节长度定义边界的二进制 payload。
• 长度字段能不能改成变长整数？可以，但读取器必须先明确变长编码的终止规则和最大编码长度，不能直接套用 4 字节帧头的逻辑。
• payload 很大时怎么办？不要无上限扩大单个切片，应重新设计为分片读取或流式消费，并继续保留单次读取上限。