Go io.ReadFull 读取定长协议帧的补齐策略

读取定长协议帧时，不能假设一次 Read 就会填满缓冲区。更稳妥的补齐策略是：固定头使用一次 io.ReadFull 读满，解析并校验负载长度后，再用第二次 io.ReadFull 读满负载。只有返回的 n == len(buf) 且 err == nil，这一段才完整；没有读到任何字节就结束是 io.EOF，只读到一部分就结束则是 io.ErrUnexpectedEOF。

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

Go net 官方文档：https://pkg.go.dev/net

我为什么不再把一次 Read 当成一帧

我最常见到的错误写法，是先创建一个 8 字节切片，然后直接调用 r.Read(header)，接着就解析魔数和长度。代码看起来直观，但 io.Reader 的契约只承诺“最多读取 len(p) 个字节”。当底层当前只有 3 个字节可用时，它完全可以返回 n=3, err=nil，剩余 5 个字节要等下一次读取。

这不是 TCP 粘包或拆包的异常，而是字节流的正常行为。网络分段、TLS 解密缓冲、代理转发、文件系统和自定义 Reader 都可能产生短读。真正值得采用的方向，不是猜一次调用会返回多少，而是把“我要一个完整固定块”写成明确的读取契约。

header := make([]byte, 8)

// 错误示例：Read 可以短读，n 小于 8 时不能解析完整头部。
n, err := r.Read(header)
if err != nil {
    return err
}
if n != len(header) {
    return fmt.Errorf("协议头短读: %d/%d", n, len(header))
}

上面的检查能发现短读，却没有完成“补齐”；调用方还得保存偏移并继续循环。io.ReadFull 已经把这段通用逻辑封装好，代码更短，也更容易在审查时看出边界。

ReadFull 解决的是完整块，不是消息边界

io.ReadFull(r, buf) 会反复从 Reader 读取，直到填满整个 buf 或遇到错误。它适合协议已知确切长度的部分，例如固定头、固定校验码、长度字段确定后的负载。它不会自己识别帧，也不会判断头部里的长度是否可信，这些仍然是协议解析器的职责。

一个容易忽略的细节是：如果底层 Reader 在已经填满缓冲区后同时返回错误，ReadFull 会丢弃该错误，因为本次请求的完整块已经获得。换句话说，调用方应以 err == nil 判断当前块完整，而不是额外猜测底层调用次数。

固定头加变长负载的完整写法

下面示例定义一个 8 字节头：前 2 字节是魔数，第 3 字节是版本，第 4 字节是标志，最后 4 字节是大端负载长度。读取顺序只有两个边界：先读满头，再按校验后的长度读满负载。

package frame

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

const (
    headerSize = 8
    frameMagic = 0xCAFE
    maxPayload = 4  maxPayload {
        return Frame{}, fmt.Errorf("负载过大: %d > %d", payloadLen, maxPayload)
    }

    payload := make([]byte, int(payloadLen))
    // 零长度负载会直接成功；非零负载必须完整填满切片。
    n, err = io.ReadFull(r, payload)
    if err != nil {
        return Frame{}, fmt.Errorf("读取负载 %d/%d 字节: %w", n, payloadLen, err)
    }

    return Frame{
        Version: header[2],
        Flags:   header[3],
        Payload: payload,
    }, nil
}

长度上限必须在 make 之前判断。否则一个伪造或损坏的 32 位长度字段可能要求进程分配数 GiB 内存。把 uint32 转成 int 也应放在上限检查之后，避免不同平台上的范围问题。

截断帧不要尝试和下一段数据拼起来

第一次采用 ReadFull 时，有人会把 io.ErrUnexpectedEOF 理解成“再读一次就能补上”。实际上，该错误表示 Reader 已经报告输入结束，而且当前固定块不完整。对于 TCP 连接，如果原因是对端关闭、连接重置或读超时，解析器通常已经失去可靠的帧边界；继续把重连后的字节接到旧帧后面，会制造更隐蔽的数据错位。

我的取舍是：完整头之前的 io.EOF 可以作为连接正常结束；任何部分头、部分负载或其他 I/O 错误都让当前帧失败。是否重连由更上层决定，但旧帧缓存不跨连接复用。只有协议本身定义了分片编号、偏移和校验，才可以实现显式续传。

网络连接还要加截止时间和取消策略

ReadFull 会一直等到缓冲区填满或底层返回错误。如果 Reader 是 net.Conn，而对端只发送了半个头后保持连接不动，没有截止时间的读取可能长期阻塞。SetReadDeadline 设置的是绝对时间，对当前被阻塞的 Read 和后续 Read 都生效，直到再次修改。

func ReadFrameFromConn(conn net.Conn, timeout time.Duration) (Frame, error) {
    // 截止时间覆盖当前及后续读取，避免半帧连接无限占用资源。
    if err := conn.SetReadDeadline(time.Now().Add(timeout)); err != nil {
        return Frame{}, fmt.Errorf("设置读截止时间: %w", err)
    }
    defer conn.SetReadDeadline(time.Time{}) // 调用结束后清除截止时间，避免污染连接复用。

    frame, err := ReadFrame(conn)
    if err != nil {
        return Frame{}, err // 保留 EOF、超时和截断错误的错误链。
    }
    return frame, nil
}

如果每读取成功一部分就希望延长“空闲超时”，需要在协议循环中更新 deadline；一个固定的绝对时间更像整帧总预算。普通 context.Context 不会自动中断裸 net.Conn.Read，应由连接截止时间、关闭连接或封装层把取消信号映射到 I/O。

手写循环、bufio.Reader 和 ReadFull 怎么选

bufio.Reader 能减少底层读取次数，也提供 Peek、ReadSlice 等能力，但它的普通 Read 仍遵守 io.Reader 契约，不保证填满传入切片。因此，即使 Reader 外面已经套了缓冲，固定块仍可以直接交给 io.ReadFull。

• 选择 io.ReadFull：长度已经确定，只关心完整块或错误，代码最清楚。
• 选择 bufio.Reader：协议含分隔符、需要窥视头部，或希望共享较大的读缓冲；固定字段仍可配合 ReadFull。
• 选择手写循环：必须在每个分片上更新校验、进度、限速或空闲超时；否则容易重复实现 n/err 边界。
• 选择 io.ReadAtLeast：只要求至少读取 min 字节，缓冲区剩余空间允许包含更多数据。

对我来说，ReadFull 最大的收益并不是少写几行循环，而是把协议审查问题从“这个循环会不会漏掉短读”变成“这里的长度从哪里来、是否已校验”。后一个问题更接近真正的协议安全边界。

上线后观察什么

采用完整块读取后，不应只统计“读取失败”。把错误按协议阶段和错误类型拆开，才能判断是客户端提前断开、链路超时、长度字段异常，还是服务端发布造成兼容问题。建议至少记录：

• 头部阶段与负载阶段的 io.EOF、io.ErrUnexpectedEOF、超时和连接重置数量；
• 声明负载长度的分布、超过上限的拒绝次数，以及零长度帧比例；
• 单帧读取耗时、连接空闲时间和同时阻塞在读取上的连接数；
• 魔数、版本和标志校验失败的计数，但日志中不要直接输出敏感负载；
• 协议版本发布前后的截断率与不兼容错误变化。

这套策略适合“长度明确”的二进制块。它不会替代协议版本协商、校验和、压缩上限、认证或重放保护。只要把完整读取、长度校验和连接生命周期分开处理，定长帧解析就会从容易偶发错位的代码，变成边界清晰、错误可观察的组件。

常见问题

io.ReadFull 会不会多读到下一帧？

不会。它最多填满传入的切片。只要切片长度正好等于当前字段或负载长度，就不会消费下一帧字节。

ErrUnexpectedEOF 后还能继续使用同一个连接吗？

通常不建议。当前固定块已经截断，帧边界不再可信。除非协议明确提供可恢复的重同步机制，否则应关闭连接并由上层决定是否重连。

已经用了 bufio.Reader，还需要 ReadFull 吗？

需要时仍要用。缓冲解决读取效率和窥视问题，不改变普通 Read 可能短读的契约；固定长度字段依然适合 ReadFull。

为什么不直接对整个连接使用 io.ReadAll？

长连接通常没有立即到来的 EOF，ReadAll 会持续等待并累积内存。帧协议应按头部和负载边界增量读取，同时限制单帧大小。