Go io.ReadAll 为什么不会把 EOF 当错误返回

io.ReadAll 不把 io.EOF 当错误返回，是因为它的任务本来就是“读取到流结束”。对底层 io.Reader 来说，EOF 是“没有更多输入”的结束信号；对已经成功读完整个流的 io.ReadAll 来说，这个信号意味着目标达成，所以最终返回已读取的数据和 nil。

标准库文档：https://pkg.go.dev/io#ReadAll

升级范围：从 ioutil.ReadAll 到 io.ReadAll

io.ReadAll 在 Go 1.16 加入标准库，用来替代旧的 ioutil.ReadAll。迁移主要是包路径变化，EOF 语义没有改：两个函数都把“正常读到末尾”视为成功。旧代码如果专门判断 err == io.EOF，那段分支本来就不会在成功的 ReadAll 调用后触发。

package main

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

func main() {
	// io.ReadAll 会持续读取，直到遇到 EOF 或其他错误。
	data, err := io.ReadAll(strings.NewReader("Go I/O"))
	if err != nil {
		// 这里处理的是非 EOF 错误，而不是正常流结束。
		panic(err)
	}

	// 成功结果是完整数据与 nil。
	fmt.Printf("%s, err=%v\n", data, err)
}

这也是官方文档直接给出的契约：成功调用返回 err == nil，而不是 err == EOF。调用方只要用通常的 if err != nil 判断即可，不需要给 EOF 写特殊分支。

变更表：底层结束信号和上层结果不是一回事

容易误解的根源，是把底层协议信号直接等同于上层操作结果。io.EOF 的名字属于 error 类型，但语义是“优雅结束输入”。是否需要向上传递，要看上层函数把什么定义为成功。

Reader 允许 n 大于零和 EOF 同时返回

io.Reader 的调用约定要求：只要 n > 0，调用方就应该先处理这 n 个字节，再解释 err。某些 Reader 会先返回最后一批数据和 nil，下一次调用再返回 0, io.EOF；另一些 Reader 可以在最后一批数据的同一次调用中返回 n > 0, io.EOF。两种形式都是调用方必须正确处理的边界。

下面构造一个 Reader，让它把最后 5 个字节和 EOF 同时返回：

package main

import (
	"fmt"
	"io"
)

type finalChunkReader struct {
	done bool
}

func (r *finalChunkReader) Read(p []byte) (int, error) {
	if r.done {
		// 后续读取没有数据，继续报告 EOF。
		return 0, io.EOF
	}

	r.done = true
	// 最后一批数据和 EOF 在同一次调用中返回。
	n := copy(p, "final")
	return n, io.EOF
}

func main() {
	data, err := io.ReadAll(&finalChunkReader{})
	// io.ReadAll 保留 final，并把正常 EOF 转成 nil。
	fmt.Printf("data=%q err=%v\n", data, err)
}

预期结果是数据为 "final"，错误为 nil。如果某个读取循环先检查 err、看到 EOF 就立刻退出，然后才处理 n，它就会丢掉最后一批数据。正确顺序始终是“先消费 n，再解释 err”。

io.ReadAll 的判断可以怎样理解

不必背实现细节，可以把它理解成三个职责：累计成功读取的字节；EOF 到来时把累计结果作为成功返回；其他错误到来时把累计结果和错误一起返回。下面是等价语义的教学版伪实现，重点在分支顺序，不用于替代标准库：

func readAllLike(r io.Reader) ([]byte, error) {
	var data []byte
	buf := make([]byte, 32*1024)

	for {
		n, err := r.Read(buf)
		if n > 0 {
			// 无论 err 是什么，先保留本次成功读取的字节。
			data = append(data, buf[:n]...)
		}

		if err == io.EOF {
			// EOF 正好完成“读到末尾”的目标，因此返回 nil。
			return data, nil
		}
		if err != nil {
			// 非 EOF 错误是异常结束，同时保留此前读取的数据。
			return data, err
		}
	}
}

标准库实现会自行管理切片容量，不能从这段教学代码推断具体分配策略。但“先保留 n 个字节、再把 EOF 视为成功”就是回答标题问题所需的核心。

旧代码风险：非 EOF 错误时 data 可能不为空

不少代码把返回值想象成二选一：有数据就没有错误，有错误就没有数据。io.ReadAll 不是这个契约。底层 Reader 可以先成功返回若干字节，再遇到磁盘、网络或解码层错误；ReadAll 会同时返回已累计数据与该错误。

package main

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

var errSource = errors.New("source interrupted")

type partialErrorReader struct {
	done bool
}

func (r *partialErrorReader) Read(p []byte) (int, error) {
	if r.done {
		// 防止示例 Reader 被继续调用后重复返回数据。
		return 0, errSource
	}
	r.done = true
	n := copy(p, "partial")
	// 返回有效字节，同时报告一个非 EOF 错误。
	return n, errSource
}

func main() {
	data, err := io.ReadAll(&partialErrorReader{})
	// data 可用于诊断，但业务不能把部分数据当完整结果。
	fmt.Printf("data=%q err=%v\n", data, err)
}

业务层应该先根据错误决定这批数据能否使用。协议报文、配置文件、签名内容这类要求完整性的输入，一旦出现非 EOF 错误，通常不能继续把部分结果当成功值；日志采集或故障诊断则可能希望保留部分内容。

新写法：从 ioutil.ReadAll 迁移

Go 1.16 之后，迁移通常只需要把导入包与调用改到 io。不要顺手增加对 EOF 的判断，也不要改变原来的成功条件。

package payload

import "io"

func Load(r io.Reader) ([]byte, error) {
	// 新代码直接使用 io.ReadAll；正常 EOF 已被转换为 nil。
	data, err := io.ReadAll(r)
	if err != nil {
		// 仅把非 EOF 读取失败交给上层。
		return nil, err
	}
	return data, nil
}

迁移前后对照如下：

ReadAll、ReadFull 和 ReadAtLeast 为什么不同

是否报告 EOF，取决于函数承诺的目标。ReadAll 的目标是读到自然结束，所以 EOF 是成功；ReadFull 的目标是填满指定缓冲区，提前结束意味着数据不够；ReadAtLeast 的目标是至少获得 min 个字节，未达到 min 就结束同样属于不完整。

package main

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

func main() {
	buf := make([]byte, 8)
	// 输入只有 3 字节，无法填满 8 字节缓冲区。
	n, err := io.ReadFull(strings.NewReader("abc"), buf)

	// ReadFull 会把中途结束报告为 io.ErrUnexpectedEOF。
	fmt.Printf("n=%d data=%q err=%v\n", n, buf[:n], err)
}

如果业务知道固定帧必须是 8 字节，就应该用 ReadFull，而不是先 ReadAll 再手动猜完整性。选择函数时先说清“完整”的定义，EOF 的处理自然就不会混乱。

回归检查：ReadAll 不会替你限制内存

io.ReadAll 会持续读取直到 EOF 或错误，因此数据源过大、永不结束或由不可信方控制时，不能直接无界读取。可以读取 max+1 字节，用多出的 1 字节判断是否超限：

package bounded

import (
	"errors"
	"io"
)

var ErrTooLarge = errors.New("input exceeds limit")

func ReadAllLimit(r io.Reader, max int64) ([]byte, error) {
	if max  max {
		// 不向上层返回超限内容，避免误当成完整结果。
		return nil, ErrTooLarge
	}
	return data, nil
}

另一个常见边界是资源关闭。io.ReadAll 只读数据，不会调用 Close。读取 HTTP 响应体或文件时，仍由打开资源的一方负责关闭。

resp, err := http.Get(url)
if err != nil {
	// 请求失败时没有可读取的响应体。
	return nil, err
}
defer resp.Body.Close() // 无论 ReadAll 是否成功，都释放连接资源。

// 对外部响应设置上限，避免无界占用内存。
data, err := bounded.ReadAllLimit(resp.Body, 4

迁移与排查清单

1. 把 ioutil.ReadAll 替换为 io.ReadAll，不要增加 EOF 特判。
2. 用 err == nil 表示 ReadAll 成功。
3. 自定义 Reader 返回 n > 0 时，确保调用方能消费这 n 个字节。
4. 非 EOF 错误发生时，不要默认 data 一定为空。
5. 需要固定长度时改用 io.ReadFull 或 io.ReadAtLeast。
6. 不可信输入增加读取上限，长流改用流式处理。
7. 对 io.ReadCloser 继续显式关闭，ReadAll 不负责资源生命周期。

小结：io.EOF 是 Reader 层的正常结束信号，不等于 ReadAll 层的失败。ReadAll 正是以 EOF 作为成功终点，所以把它转换成 nil；真正需要向调用方报告的是非 EOF 错误。理解这层契约后，EOF 特判、最后一批数据丢失以及 ReadAll 与 ReadFull 混用的问题都会更容易排查。