Go io.Reader 怎样按固定字节数读取网络帧

我第一次给 TCP 长连接加自定义协议时，最先踩到的坑不是字节序，而是把一次 Read 当成了一整帧。TCP 只提供连续字节流，调用方拿到的字节数可能小于目标长度。固定帧协议更稳妥的做法是先读取完整帧头，再解析长度，最后用 io.ReadFull 把帧体读满。

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

固定长度读取的关键不是“多调用几次 Read”，而是把“目标长度、已读字节数和错误类型”交给明确的读取契约。帧头和帧体都应使用 io.ReadFull，长度字段在分配内存前先做上限判断。

这条标准库能力解决的是什么问题

从标准库的角度看，io.Reader 只承诺“本次调用返回已经拿到的字节”，不承诺填满传入的切片。网络抖动、内核缓冲区状态和对端发送节奏都可能让一次读取只得到一部分数据。io.ReadFull 则把目标变成“读到切片填满，或者明确返回错误”。

对我来说，这个区别很实用：协议层不再猜测一次 Read 是否碰巧拿到了完整消息，读取层和解析层之间也有了稳定边界。下面的例子把帧定义为 4 字节大端序长度加上 payload，实际协议若使用魔数、版本或校验和，也可以沿着同一思路扩展帧头。

我第一次处理 TCP 帧时，先把长度边界画出来

帧头的长度必须是协议的一部分，而不是根据当前缓冲区“看起来有多少”来决定。读取 4 字节头部后，再用 binary.BigEndian.Uint32 把它解释为 payload 长度。这里示例使用大端序只是协议约定；如果对端约定小端序，就要对应使用 binary.LittleEndian。

package frame

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

const maxPayload = 1  maxPayload {
        return nil, fmt.Errorf("payload too large: %d", payloadLen)
    }

    payload := make([]byte, int(payloadLen))
    // 帧头和帧体分开读取，避免把半个下一帧混进当前消息。
    if _, err := io.ReadFull(r, payload); err != nil {
        return nil, fmt.Errorf("read frame payload: %w", err)
    }
    return payload, nil
}

这个函数的关键点有三个：帧头和帧体都按协议长度读取；长度上限在内存分配前检查；底层错误用 %w 包装，调用方仍能通过 errors.Is 判断是否属于 io.ErrUnexpectedEOF 等已知情况。

和直接调用 Read 相比，固定读取的体验差在哪里

我一开始写过下面这种更短的代码：分配一个帧体切片，调用一次 r.Read(payload)，然后把返回的 n 当成完整消息长度。它在本地发送速度稳定时很容易“看起来能用”，但协议边界已经被交给了网络分片结果。

func readFrameOnce(r io.Reader, payload []byte) ([]byte, error) {
    // 这只是一次尝试，Read 返回的 n 可能小于 len(payload)。
    n, err := r.Read(payload)
    if err != nil {
        return nil, err
    }
    // 不应把短读静默当成完整帧，否则下一次读取会从半帧中间开始。
    if n != len(payload) {
        return nil, io.ErrUnexpectedEOF
    }
    return payload, nil
}

如果业务确实允许“拿到多少处理多少”，直接 Read 没问题；但固定长度协议需要的是完整性，不是一次调用的即时返回。io.ReadFull 内部基于 ReadAtLeast 反复读取，并把“没有读满”转换为明确的错误结果，边界表达更直接。

我最后真正关心的是 n 和 err 的组合

io.ReadFull 返回 n 和 err，不要只判断 err == nil。目标切片完全填满时返回完整长度和 nil；如果一字节都没有读到就遇到结束，通常得到 io.EOF；如果读到一部分后连接结束，则是 io.ErrUnexpectedEOF。底层 Reader 返回的其他错误也应保留，不能一概改成 EOF。

func classifyFrameRead(r io.Reader, size int) error {
    payload := make([]byte, size)
    // n 反映已写入 payload 的字节数，err 反映读取是否完成或为何中断。
    n, err := io.ReadFull(r, payload)
    if err == nil {
        // n == size，调用方此时才可以把 payload 当作完整帧体。
        return nil
    }

    if err == io.EOF && n == 0 {
        // 没有新帧且对端正常结束，可由上层决定关闭连接。
        return io.EOF
    }
    if err == io.ErrUnexpectedEOF {
        // 已收到半帧，不能把残留字节交给下一轮协议解析。
        return fmt.Errorf("incomplete frame: got %d of %d bytes: %w", n, size, err)
    }
    // 连接超时、取消或自定义 Reader 错误都要保留原始原因。
    return fmt.Errorf("read frame: %w", err)
}

在实际服务里，我通常还会用 errors.Is 判断包装后的错误，并给连接设置读取截止时间。这样“对端关闭”“半帧断开”“读取超时”和“协议长度不合法”在日志里是不同类别，重试或关闭策略也不会混在一起。

把它放进长连接循环时，边界要写在分配之前

固定帧读取的另一个代价是：帧头里的长度来自网络，不能盲目信任。除了单帧上限，还要考虑空 payload 是否合法、帧头是否包含版本或魔数、连接是否设置了 deadline，以及当帧体不完整时是否立即关闭连接。io.ReadFull 只负责读取契约，不替协议层做安全策略。

func serveFrames(conn io.Reader) error {
    for {
        frame, err := readFrame(conn)
        if err != nil {
            // EOF 表示没有下一帧；其它错误交给上层记录和决定是否重连。
            if err == io.EOF {
                return nil
            }
            return err
        }
        // 这里交给业务处理一帧；处理函数不应读取下一帧的字节。
        if err := handleFrame(frame); err != nil {
            return err
        }
    }
}

示例中的 handleFrame 是业务边界，占位函数没有展示具体实现。若协议还需要校验和或消息类型，可以在 readFrame 返回前完成帧级校验；若单帧上限超出约定，则应尽早拒绝，而不是先分配再判断。

我的结论：适合固定边界，不适合所有流式数据

如果协议已经定义了固定长度头部和长度字段，io.ReadFull 是我会优先采用的最小工具：它让短读不再靠运气，让错误携带实际读取进度，也能自然嵌入 TCP 长连接循环。它不适合替代按分隔符读取、消息队列消费确认或允许增量处理的大文件流；这些场景需要 bufio.Reader、流式解码器或业务级背压。

• 固定帧头：先用 io.ReadFull 读满，再解析长度和协议字段。
• 固定帧体：先做最大长度判断，再分配并读满目标切片。
• 错误判断：结合 n 和 err，区分 EOF、半帧和底层错误。
• 长连接：为读取设置 deadline，并把不完整帧视为当前连接的异常状态。

常见问题

io.ReadFull 会把下一帧的字节读进当前帧吗？不会。它只填满传入的目标切片；前提是协议层正确提供了当前帧长度。

读取固定帧一定要用 TCP 吗？不是。任何实现了 io.Reader 的来源都可以使用，包括文件、内存缓冲区和连接；这里只讨论 TCP 字节流最常见的帧边界问题。

为什么半帧返回 io.ErrUnexpectedEOF？因为目标长度已经确定，但 Reader 在填满之前结束，调用方需要知道这是不完整数据，而不是一条正常结束消息。