Go Reader 返回 n 大于零和 EOF 时应该先处理哪个

当 io.Reader.Read 同时返回 n > 0 和 io.EOF 时，应该先处理 buf[:n]，再处理 EOF。EOF 说明输入流已经结束，却不会让这次已经读到的字节失效；如果先看到 EOF 就退出，最后一段数据会被直接丢掉。

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

标准库源码：https://go.dev/src/io/io.go

通用判断顺序只有两层：只要 n > 0 就消费数据；消费完成后，再把 io.EOF 当作正常结束，把其他非空错误当作读取失败。

为什么 n 大于零和 EOF 可以同时出现

Reader 的签名是 Read(p []byte) (n int, err error)。其中 n 描述这次放进缓冲区的有效字节数，err 描述读取边界或错误状态。二者不是“只能成功一个”的互斥关系。

输入流恰好剩下一小段数据时，实现可以选择两种合法方式：

调用方必须同时兼容这两种行为，不能依赖某个具体 Reader 恰好采用哪一种。标准库文档明确要求：只要 n > 0，就应先处理返回的字节，再考虑 err。

正确循环先消费数据，再判断错误

下面的写法把数据处理和错误处理分开。关键不是把 EOF 放在哪个 switch 分支，而是确保 n > 0 的数据分支排在错误分支之前。

package stream

import (
    "io"
)

func consumeAll(r io.Reader, consume func([]byte) error) error {
    // 缓冲区只在当前循环内复用，消费方如需长期保存必须自行复制。
    buf := make([]byte, 32*1024)

    for {
        n, err := r.Read(buf)

        if n > 0 {
            // 先处理本次有效区间，不能把整个 buf 都交出去。
            if consumeErr := consume(buf[:n]); consumeErr != nil {
                return consumeErr
            }
        }

        if err != nil {
            if err == io.EOF {
                // EOF 是正常结束；到这里时尾部数据已经处理完。
                return nil
            }
            // 非 EOF 错误在已读数据处理后向上传递。
            return err
        }
    }
}

这里还有一个容易被忽略的细节：只能读取 buf[:n]。buf[n:] 可能保留上一次循环的旧内容，把整个缓冲区交给下游会制造重复或脏数据。

一个会丢尾部数据的常见写法

下面的代码先检查错误。只要某个 Reader 合法地返回 n > 0, io.EOF，循环就会在数据处理之前退出。

for {
    n, err := r.Read(buf)
    if err == io.EOF {
        // 错误：此时 n 可能大于零，直接退出会丢掉最后一段数据。
        break
    }
    if err != nil {
        // 这里也可能跳过与普通错误同次返回的有效字节。
        return err
    }

    // 这段代码只有在 err 为 nil 时才运行，覆盖不了全部 Reader 契约。
    consume(buf[:n])
}

这种 bug 往往不容易在开发环境出现，因为 os.File、bytes.Reader 或网络连接的具体返回节奏可能不同。接口调用方应该按 io.Reader 契约编程，而不是按某次测试观察到的节奏编程。

普通错误也要在已读数据之后处理

n > 0 与非 EOF 错误也可以同时出现。比如底层读取在取得部分数据后遇到设备或连接错误。通用原则仍然是先把这次已读数据交给消费逻辑，再返回读取错误。

不过，消费错误和读取错误同时存在时，应用需要定义自己的错误优先级。最常见的策略是：

• 消费函数先失败：立即返回消费错误，因为数据并未被业务成功接收。
• 消费成功、读取同时失败：返回读取错误，已消费字节仍然算有效。
• 消费动作不可重复：让消费方在内部保证幂等，避免上层重试时重复写入。

如果业务必须同时保留两个错误，可用包装错误或自定义结构记录，但不要为了保留错误而跳过 p[:n]。

0,nil 不是 EOF，也不代表读取完成

除非传入的缓冲区长度为零，Reader 实现通常不应返回 0, nil，但调用方仍不能把它当作 EOF。这个组合只表示本次没有数据、也没有明确错误。

func readWithNoProgressLimit(r io.Reader, consume func([]byte) error) error {
    buf := make([]byte, 4096)
    idle := 0

    for {
        n, err := r.Read(buf)
        if n > 0 {
            idle = 0 // 只要取得数据，就清空无进展计数。
            if consumeErr := consume(buf[:n]); consumeErr != nil {
                return consumeErr
            }
        } else if err == nil {
            idle++
            if idle >= 100 {
                // 防止异常 Reader 让当前循环长期空转。
                return io.ErrNoProgress
            }
        }

        if err != nil {
            if err == io.EOF {
                return nil // 尾部数据已在前面消费。
            }
            return err
        }
    }
}

是否需要这样的无进展上限，取决于 Reader 的来源与调用场景。它是一项防御策略，不是把 0,nil 重新定义为 EOF。

不需要自定义循环时优先使用标准库

很多场景不必自己处理每一次 Read：

标准库已经封装了 EOF 语义。只有当你需要逐块解码、流式校验、限速、增量哈希或把每块交给自定义消费者时，才更适合直接编写 Read 循环。

容易混淆的几个边界

n 大于零时 err 一定是 nil 吗？

不一定。Reader 可以把本次读到的字节与 EOF 或其他错误一起返回。

看到 EOF 后还要再调用一次 Read 吗？

如果当前调用已经返回 EOF，就不需要为了确认结束再读一次；先消费本次 p[:n]，然后结束即可。如果当前调用是 n > 0, nil，则需要继续读取，后续调用可能返回 0, EOF。

可以用 errors.Is(err, io.EOF) 吗？

io.Reader 契约要求正常 EOF 直接返回 io.EOF，标准写法通常使用 err == io.EOF。如果上层组件把错误包装后另有约定，应按该组件文档处理，不能改变基础 Reader 契约。

为什么 io.Copy 成功时不是返回 EOF？

因为 io.Copy 的任务就是复制到输入结束。对它来说，EOF 是预期完成条件，所以成功结果是 err == nil。

最后记住这一条判断顺序

处理 io.Reader 时，不要把 err 当作本次数据是否有效的开关。先根据 n 消费 p[:n]，再根据 err 决定继续、正常结束或返回失败。这样既不会丢掉尾部数据，也能兼容 Reader 契约允许的全部 EOF 返回方式。