Go io.ReadFull 读取二进制头部时如何安排缓冲区

解析二进制协议时，io.ReadFull 的缓冲区应该跟协议字段绑定，而不是先开一块“足够大”的数组。固定头部用固定长度的 headerBuf，从头部读出载荷长度并完成上限校验后，再创建独立的 payloadBuf。这样既不会把半个头部误当成完整头部，也不会因为恶意长度字段直接申请过大的内存。

官方文档：https://pkg.go.dev/io#ReadFull

先把二进制包拆成两个读取边界

假设协议头固定为 8 字节：前 4 字节是魔数，接着 2 字节是版本，最后 2 字节表示载荷长度。读取头部时只申请 8 字节，ReadFull 成功后再解释字段。不要把载荷缓冲区提前拼进头部数组，否则一旦长度字段异常，定位和回收都会变得模糊。

校验长度字段后再安排载荷缓冲区

下面的写法把“读取边界”和“安全上限”放在同一个解析函数里。示例使用大端序，真实项目要以协议文档为准；maxPayload 不是越大越好，而是应该和单条消息允许的业务规模一致。

func readFrame(r io.Reader) ([]byte, error) {
    const (
        headerSize = 8
        maxPayload = 4  maxPayload {
        // 先拒绝过大的长度，再创建 payloadBuf，避免无界内存申请。
        return nil, fmt.Errorf("载荷长度 %d 超过上限 %d", payloadLen, maxPayload)
    }

    payloadBuf := make([]byte, payloadLen)
    if n, err := io.ReadFull(r, payloadBuf); err != nil {
        // 载荷边界独立记录，日志中不要只打印一个模糊的 EOF。
        return nil, fmt.Errorf("读取载荷失败，已读 %d/%d 字节: %w", n, payloadLen, err)
    }
    return append(headerBuf, payloadBuf...), nil
}

这里没有假设底层 Read 一次就能返回全部数据。网络连接、文件包装器和自定义 Reader 都可能产生短读，ReadFull 会持续读取直到填满目标切片或遇到错误。真正需要防护的是长度字段：它来自输入，必须先经过字段宽度、最大值和整数转换检查。

按 n 和错误值判断短读原因

ReadFull 的判断规则很适合直接写进日志和重试策略：输入一开始就结束时通常是 io.EOF；已经读到一部分但没填满目标切片时是 io.ErrUnexpectedEOF；只有 n == len(buf) 才能把这次读取当作成功。错误可能被包装，所以业务分支应使用 errors.Is。

n, err := io.ReadFull(r, headerBuf)
switch {
case err == nil:
    // 只有完整头部才能继续解释长度字段。
case n == 0 && errors.Is(err, io.EOF):
    // 没有读到任何字节，连接可能是正常结束或没有下一帧。
case errors.Is(err, io.ErrUnexpectedEOF):
    // 已收到部分头部或载荷，当前帧已经截断，通常不应继续解码。
default:
    // 记录底层网络、文件或自定义 Reader 返回的其他错误。
}

如果协议允许多帧连续读取，可以把“空输入”视为流结束，把“半帧”视为损坏并丢弃当前连接；如果协议要求严格传输，则两者都应该进入失败指标。关键是不要用“只要没有 panic 就算成功”的判断，也不要忽略返回的 n。

把边界检查固定成解析清单

• 头部长度是否是协议常量，且每次读取都使用独立切片。
• 长度字段的字节序、字段宽度和转成 int 前的范围是否明确。
• 载荷上限是否先于 make 执行，拒绝后是否没有继续读取。
• 日志是否包含区域名称、n、目标长度和可匹配的原始错误。
• 连接复用时，截断帧是否会污染下一帧，必要时是否关闭或重新同步。

缓冲区安排的本质不是“申请多大才够”，而是让每一个切片都对应一个明确的协议边界。边界越清楚，长度校验、错误处理和后续解码越容易分别测试。

常见问题

为什么不用一次 Read 读取头部？

一次 Read 只表示当前调用拿到的字节数，不保证填满切片。固定长度字段需要完整语义时，用 ReadFull 更直接。

载荷长度为零还要调用 ReadFull 吗？

可以调用，零长度切片不会等待载荷；也可以把零长度作为协议允许的空载荷直接返回，但要保持头部读取和长度校验已经完成。

ErrUnexpectedEOF 能不能当成普通 EOF？

不建议。普通 EOF 可能表示流中没有下一帧，ErrUnexpectedEOF 说明当前字段已经开始却没有完成，通常应记录为截断或协议错误。