io.Reader 为什么允许同时返回数据和 EOF，调用方应怎样处理

我在处理流式响应时，最容易误判的一件事就是把 err != nil 直接当成“本轮没有数据”。对 io.Reader 来说，这个判断顺序是反的：只要 n > 0，就必须先消费 p[:n]；之后再处理 err。因此，最后一小段数据可以和 io.EOF 在同一次调用里返回，调用方也不能丢掉它。

一、返回值先看 n，再处理 err

Read 的返回值同时描述两件事：这一次写入了多少字节，以及这次调用是否已经遇到结束或其他错误。Go 官方接口契约明确要求调用方先处理 n > 0 的数据，再看 err。这样既能接住末尾数据，也不会漏掉“读到一半才发生”的真实错误。

func consume(r io.Reader) error {
    buf := make([]byte, 8)
    for {
        n, err := r.Read(buf)
        if n > 0 {
            // 先消费本轮真实数据，不能因为 err 非空就跳过。
            use(buf[:n])
        }
        if err != nil {
            // EOF 表示正常结束，其他错误必须继续向上报告。
            if err == io.EOF {
                return nil
            }
            return err
        }
    }
}

这里的关键不是某个具体 Reader 会返回哪一种组合，而是调用方必须兼容两种合法行为：最后一批数据可以带 io.EOF，也可以先返回数据和 nil，下一次再返回 0, io.EOF。

二、数据和 EOF 为什么可以同次返回

Reader 面向的是字节流，而不是固定大小的记录。假设缓冲区还有 8 个字节空间，但输入只剩 3 个字节，底层实现已经知道“这 3 个字节就是末尾”。它可以返回 n=3 同时报告 io.EOF，也可以把结束信号留到下一次调用。两种写法都不会改变已经读到的 3 个字节。

所以，io.EOF 不是“本轮没有返回数据”的同义词，而是“输入已经正常结束”的信号。反过来，0, nil 也不代表 EOF；它只说明这次没有拿到数据，Reader 不应长期这样返回，调用方更不能据此直接宣布结束。

三、手写读取循环与 io.Copy 的边界

如果只是把一个 Reader 的全部内容交给 Writer，优先使用 io.Copy，它已经按“先处理字节、再处理错误”的规则完成循环。只有需要解析每一块数据时，才手写读取逻辑，并保留 n > 0 分支。

固定长度读取是另一种语义：调用方要求“必须拿到指定数量的字节”。这时可以使用 io.ReadFull：

func readHeader(r io.Reader) ([]byte, error) {
    header := make([]byte, 16)
    n, err := io.ReadFull(r, header)
    if err != nil {
        // 读到一部分就结束，说明结构不完整，不是普通 EOF。
        if err == io.ErrUnexpectedEOF {
            return nil, fmt.Errorf("header truncated after %d bytes: %w", n, err)
        }
        return nil, err
    }
    return header, nil
}

流式消费可以把正常 EOF 当作结束；固定结构则必须区分“一个字节都没有，输入为空”和“已经读到一部分却不够”。这就是 io.EOF 与 io.ErrUnexpectedEOF 的边界。

四、常见误区与排查清单

第一，不要写成“只要 err != nil 就 return”，否则同次返回的尾部字节会被丢弃。第二，不要用 n == 0 推断结束，真正的结束判断是 err == io.EOF。第三，io.Reader 的 EOF 契约要求直接返回 io.EOF，调用方通常用相等比较识别它；业务错误可以保留上下文，但不要把正常 EOF 包装成无法识别的值。

排查读取异常时，可以按这个顺序看：本轮 n 是否大于零；是否已经消费 buf[:n]；err 是 EOF、ErrUnexpectedEOF 还是底层错误；调用方到底需要“读到结束”还是“读满固定长度”。把这四项分开，绝大多数“少读尾部数据”和“把截断当成功”的问题都能定位。

相关问题

io.Reader 返回 0, nil 时应该立即退出吗？

不应该把它当作 EOF。它表示本次没有发生有效读取；可以继续尝试，但如果同一个 Reader 长时间重复返回 0、nil，应按无进展或实现异常处理，避免忙等。

什么时候应该直接用 io.ReadAll？

当输入规模可控且确实需要完整字节切片时可以使用；大文件、长连接或需要边读边处理的场景应保留流式循环，避免一次性占用不可控的内存。