Go 把 io.EOF 当成业务错误为什么误报

很多 Go 程序把读取循环里的 io.EOF 直接记成“业务失败”，结果文件读完报错、网络流正常收尾也被监控标红。它通常只是输入已经耗尽：对普通流来说应当结束循环；只有结构化数据在中途缺尾，才需要升级为异常。处理 io.Reader 时还要先消费 n > 0 的数据，再判断 err。

先记住这张表：

io.Reader 循环为什么会把 EOF 误报成失败

Reader.Read 允许一次调用同时拿到数据和错误，也允许把错误留到下一次调用。因此不能先写“只要 err != nil 就返回”。先处理 n，再把 EOF 当作循环结束，才能覆盖这两种合法实现。

func consume(r io.Reader, handle func([]byte) error) error {
    buf := make([]byte, 32*1024) // 固定缓冲区，避免把整个输入一次性读入内存
    for {
        n, err := r.Read(buf)
        if n > 0 {
            if handleErr := handle(buf[:n]); handleErr != nil {
                return handleErr // 业务处理失败，不要被后面的 EOF 覆盖
            }
        }
        if err == io.EOF {
            return nil // 输入正常耗尽，不是业务错误
        }
        if err != nil {
            return fmt.Errorf("读取输入失败: %w", err) // 保留底层错误供上层判断
        }
    }
}

这里的顺序有两个关键点：buf[:n] 只交给业务本次真实读取的部分；io.EOF 在数据处理之后才被解释为正常结束。若直接先返回错误，最后一批数据可能丢失；若把 EOF 统一上报，又会把正常文件结束制造成故障。

固定长度记录要用 ErrUnexpectedEOF 判断截断

普通流读完可以自然结束，但固定长度的消息、文件头或二进制记录有完整性要求。此时“读到 EOF”不一定等价于正常：如果一个字节都没读到，可以表示没有下一条记录；如果已经读到一部分却没凑齐目标长度，应识别为 io.ErrUnexpectedEOF。

func readFrame(r io.Reader, size int) ([]byte, error) {
    frame := make([]byte, size) // 协议约定的固定长度记录
    n, err := io.ReadFull(r, frame)
    if err == io.EOF && n == 0 {
        return nil, io.EOF // 没有下一条记录：交给上层结束循环
    }
    if err == io.ErrUnexpectedEOF {
        return nil, fmt.Errorf("记录只有 %d/%d 字节: %w", n, size, err) // 中途缺尾
    }
    if err != nil {
        return nil, fmt.Errorf("读取记录失败: %w", err) // 网络或文件等真实错误
    }
    return frame, nil // 只有完整记录才进入解析或校验层
}

业务层可以据此做明确决策：io.EOF 表示“没有下一条”，io.ErrUnexpectedEOF 表示“当前记录不完整”，其他错误表示读取链路本身失败。不要只比较错误字符串，也不要为了消除日志把所有错误都改成 EOF。

把 EOF 误报排除掉的回归检查

修改后至少覆盖四组输入：空输入、恰好完整的输入、最后一次返回数据并同时返回 EOF 的 Reader、只返回半条固定长度记录的 Reader。再补一组真实错误，例如底层 Reader 返回自定义错误，确认它不会被吞掉。

• 普通拷贝或连续读取：结束时返回 nil，而不是把 EOF 传给业务告警。
• 固定长度读取：零字节 EOF 可结束循环，部分数据 EOF 要落为 ErrUnexpectedEOF。
• 监控和日志：正常收尾使用 debug 或不记录错误，真正的非 EOF 错误保留原始链路。

还要注意，io.ReadAll、io.Copy 等高层工具通常已经把正常 EOF 消化掉，成功时直接返回 nil。只有在自己实现读取协议、逐条解码或封装 Reader 时，才需要显式区分这些状态。

相关问题

为什么不能只写 if err != nil { return err }？ 因为一次 Read 可能同时返回数据和错误，先处理 n > 0 才不会丢掉末尾数据；EOF 还需要单独解释为正常结束。

什么时候应该使用 errors.Is？ 当你判断被包装的业务错误或其他哨兵错误时可以使用它；标准 Reader.Read 的 EOF 契约要求直接返回 io.EOF，调用方通常按 err == io.EOF 处理。