Go ReadFull 返回 EOF 和 UnexpectedEOF 有什么区别

用 io.ReadFull 读取固定长度的消息头、二进制字段或协议负载时，EOF 和 UnexpectedEOF 不是同一个问题：前者表示一个字节都没有读到，后者表示已经读到一部分，但数据在固定块完成前就结束了。判断是否成功不能只看错误字符串，而要同时看 n 和 err。

对 io.ReadFull(r, buf) 来说，n == len(buf) 且 err == nil 才代表固定长度块完整；n == 0 的 EOF 通常可视为输入正常结束，而 0 时的 io.ErrUnexpectedEOF 说明结构化数据被截断。

io.ReadFull 的成功条件为什么是 n == len(buf)

io.Reader 一次返回多少字节并不固定。网络连接、文件和内存读取器都可能分多次交付数据，所以普通的 Read 不能保证一次填满缓冲区。ReadFull 把“必须拿到完整块”这个约束集中到一个调用里。

它的返回值可以先按这个表理解：

EOF 和 UnexpectedEOF 分别说明了什么

官方 io 文档把 io.EOF 定义为“没有更多输入可读”。在 ReadFull 中，如果第一次尝试就没有读到任何字节，返回 io.EOF；这适合表示消息流在下一个完整块开始前自然结束。

如果已经读到了一部分，说明调用方已经看到了一个块的开头，此时再遇到 EOF 就不能当作自然结束。ReadFull 返回 io.ErrUnexpectedEOF，它表达的是“固定大小的数据结构在中间结束”。例如协议头要求 8 字节，却只收到 3 字节，这个包应视为损坏或传输不完整。

不要用 err.Error() == "unexpected EOF" 比较字符串。错误可能被包装，应该使用 errors.Is：

package main

import (
    "errors"
    "fmt"
    "io"
    "strings"
)

func readBlock(r io.Reader, size int) error {
    // 缓冲区长度就是协议要求的固定块长度。
    buf := make([]byte, size)
    n, err := io.ReadFull(r, buf)
    switch {
    case err == nil:
        // 只有填满整个缓冲区，数据才可以交给解析器。
        fmt.Printf("完整块：%d 字节\\n", n)
        return nil
    case errors.Is(err, io.EOF) && n == 0:
        // 一个字节都没有，表示输入在新块开始前结束。
        return io.EOF
    case errors.Is(err, io.ErrUnexpectedEOF):
        // 记录 n，便于日志说明实际收到多少字节。
        return fmt.Errorf("固定块被截断：已读 %d/%d 字节：%w", n, size, err)
    default:
        // 其他错误仍保留底层原因，避免丢失网络或文件错误。
        return fmt.Errorf("读取固定块失败：%w", err)
    }
}

func main() {
    // 示例输入少于要求的 8 字节，用来说明截断分支。
    _ = readBlock(strings.NewReader("abc"), 8)
}

调用方该怎样设计错误分支

协议解析器通常需要把“连接正常关闭”和“半包”分开。对消息循环来说，io.EOF 且 n == 0 可以结束循环；io.ErrUnexpectedEOF 则应该记录上下文、丢弃当前消息，或交给上层决定是否重试。二者都不适合直接忽略。

还要注意一个容易误判的边界：如果底层 Reader 在已经满足 len(buf) 后同时返回了一个错误，ReadFull 会认为固定块已完成并丢弃该错误。因此调用方以 n == len(buf) 且 err == nil 作为成功条件，不能靠“读到过一些字节”判断成功。

把固定长度读取放进协议解析

一个常见做法是先读固定头部，再从头部得到负载长度，然后为负载分配缓冲区并再次调用 ReadFull。头部完整但负载不完整时，错误应带上当前消息长度，方便排查是发送端声明错误还是连接提前关闭。

func readPayload(r io.Reader, payloadSize int) ([]byte, error) {
    // 先限制长度，避免把异常头部变成超大内存申请。
    if payloadSize  4*1024*1024 {
        return nil, fmt.Errorf("非法负载长度：%d", payloadSize)
    }
    payload := make([]byte, payloadSize)
    n, err := io.ReadFull(r, payload)
    if err != nil {
        // 返回已读数量，让上层区分空输入、半包和底层故障。
        return nil, fmt.Errorf("读取负载 %d/%d 字节失败：%w", n, payloadSize, err)
    }
    return payload, nil
}

这段逻辑的关键不是“多试几次”，而是把长度字段、目标缓冲区和错误模型绑定起来。重试前应先确认 Reader 是否可重放；对 TCP 流盲目重试同一个 ReadFull，通常只会继续等待剩余字节，不会修复已经丢失的数据。

常见问题

ReadFull 返回 EOF 时是不是一定没有错误？

不是。它表示这次固定块读取没有拿到任何字节；在消息循环中可能是正常结束，在必须存在消息的协议里也可能代表对端过早关闭，仍要结合协议语义判断。

UnexpectedEOF 能不能当成 EOF 处理？

通常不能。它说明已经读到结构的一部分，继续解析会把残缺数据当成完整字段，应该丢弃当前块或进入明确的恢复流程。

为什么还要保留 n？

n 能说明截断发生在什么位置，也能帮助日志和指标区分空输入、短包与底层 I/O 失败。