Go io.ReadFull 怎样区分提前结束和读取失败

处理固定长度的协议头、二进制字段或文件块时，普通 Read 读到多少就返回多少，调用方不能把一次返回当成“已经读完整”。io.ReadFull 的判断规则更明确：只有 n == len(buf) 且 err == nil 才算完整；没有读到任何字节的 EOF、读到一部分后提前结束，以及底层 I/O 错误要分别处理。

直接结论：先看 n 是否等于目标缓冲区长度，再看 err。空读到结尾通常是 io.EOF；部分读取后遇到结尾，io.ReadFull 会返回 io.ErrUnexpectedEOF；如果底层返回的是其他错误，就保留那个错误。读取已经满足长度时，底层同时带来的错误会被视为已完成并丢弃。

官方地址：https://pkg.go.dev/io#ReadFull

先记住 io.ReadFull 的返回边界

io.ReadFull(r, buf) 实际上要求读取恰好 len(buf) 个字节。它返回的 n 是已经复制到 buf 的数量，err 则说明为什么没有达到目标，或者为什么读取完成。最重要的契约是：n == len(buf) 当且仅当 err == nil。

package main

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

func main() {
	buf := make([]byte, 8)
	n, err := io.ReadFull(strings.NewReader("header"), buf)

	// n 先说明读到了多少；err 再说明为什么没有凑够固定长度。
	if n == len(buf) && err == nil {
		fmt.Printf("完整读取：%q\n", buf)
		return
	}

	// 这里的 n 仍然有价值，错误处理不能只打印 err 就结束。
	fmt.Printf("读取不完整：n=%d/%d err=%v\n", n, len(buf), err)
}

上例的输入只有 6 个字节，因此它不是“读到 6 个字节就成功”，而是固定长度读取失败。ReadFull 会把“部分数据后遇到 EOF”转换为 io.ErrUnexpectedEOF，这样调用方能知道数据在结构中间被截断。

四种结果不要混成一个“读取失败”

实际排障时，可以把结果分成四类。第一类是 n == len(buf), err == nil，表示目标已经填满。第二类是 n == 0, err == io.EOF，表示输入从一开始就没有数据。第三类是 0 ，表示数据读到一半就结束。第四类是 n 且错误不是 EOF 哨兵，通常意味着底层连接、文件或自定义 Reader 真正报错。

package reader

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

func classifyRead(n, want int, err error) error {
	if err == nil && n == want {
		return nil
	}
	if errors.Is(err, io.EOF) && n == 0 {
		// 没有消费任何字节，调用方可把它当作自然结束。
		return fmt.Errorf("输入为空：%w", io.EOF)
	}
	if errors.Is(err, io.ErrUnexpectedEOF) {
		// 结构读到中间被截断，不能当作普通文件结束。
		return fmt.Errorf("固定长度数据只收到 %d/%d 字节：%w", n, want, io.ErrUnexpectedEOF)
	}
	if err != nil {
		// 保留底层错误，让上层仍可用 errors.Is 或 errors.As 判断。
		return fmt.Errorf("读取固定长度数据失败：%w", err)
	}
	return fmt.Errorf("读取结果异常：n=%d/%d", n, want)
}

这里用 errors.Is 而不是只比较错误文本，是因为上层可能已经给错误增加了上下文。需要注意的是，只有在 err != nil 且没有读满时才进入错误分支；不要因为 n 小于目标长度就自行把一个自定义错误改写成 ErrUnexpectedEOF。

固定长度协议头要把错误上下文带回业务层

在二进制协议中，读取 4 字节长度、16 字节版本或固定头部时，最怕把截断和正常结束混为一谈。标准库只负责给出读取边界，协议读取器应补充“正在读取哪个字段”的上下文，但不要覆盖原始错误：

package protocol

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

func readHeader(r io.Reader) (uint32, error) {
	var raw [4]byte
	if _, err := io.ReadFull(r, raw[:]); err != nil {
		// %w 保留 EOF 或 ErrUnexpectedEOF，字段名补充协议上下文。
		return 0, fmt.Errorf("读取长度头失败：%w", err)
	}

	// 只有 ReadFull 成功后才解释字节序，避免解析半个头部。
	return binary.BigEndian.Uint32(raw[:]), nil
}

当输入完全为空时，错误链中仍是 io.EOF；当输入只有 2 个字节时，错误链中是 io.ErrUnexpectedEOF。上层可以据此区分“没有下一条记录”和“记录损坏或传输被截断”，而不是只看到一条无法行动的字符串。

不要把 Read、ReadAtLeast 和 ReadFull 当成同一种契约

普通 Read 只承诺“最多读入 len(p) 个字节”，适合流式消费；io.ReadAtLeast 只要求达到指定的最小数量；io.ReadFull 则把最小数量固定为整个缓冲区长度。选择错误的函数，往往会让边界条件在后面才暴露。

• 流式数据：每次能处理多少就处理多少，使用普通 Read，不要自行假设一次读满。
• 最少字节数：只要达到阈值就可以继续，考虑 io.ReadAtLeast，并处理 io.ErrShortBuffer。
• 固定长度字段：必须拿到完整缓冲区再解析，使用 io.ReadFull。
• 错误包装：给字段或阶段增加上下文时使用 %w，不要只拼接错误文本。

我在排查这类问题时，会先把目标长度写在日志上下文里，再同时记录 n 和错误类型。这样可以快速判断是“没有下一条数据”、 “数据只到一半”，还是底层 Reader 已经失败。不要运行时凭错误字符串猜测输入是否完整，固定长度读取的可靠信号就是 n == len(buf) 且 err == nil。

相关问题

为什么读到部分数据时不是普通 io.EOF？

因为固定长度结构已经开始读取但没有完成，io.ReadFull 用 io.ErrUnexpectedEOF 表达“在结构中间结束”，方便上层把它与自然结束区分。

n 已经等于目标长度但 err 不为空怎么办？

按照 ReadFull 的契约，达到目标长度时返回成功，底层在同次读取中携带的错误会被丢弃。调用方应以 n == len(buf) 且 err == nil 为完整读取条件。

可以只判断 err == io.EOF 吗？

不建议。还要看 n，并处理 io.ErrUnexpectedEOF 以及其他底层错误；错误可能被包装时，应使用 errors.Is。

ReadFull 会自动重试网络连接吗？

不会。它只在同一个 io.Reader 上继续读取直到满足长度或遇到错误，重连、退避和幂等性属于业务层策略，不是 ReadFull 的职责。

资料入口：https://pkg.go.dev/io#ReadFull；实现说明：https://go.dev/src/io/io.go。