io TeeReader 出错时为什么由写端返回错误

在 Go 里，io.TeeReader 很适合把同一段输入同时交给读取方和一个旁路写入方。它最容易让人误判的地方是：写端不是“后台记录”，而是当前读取的一部分。只要 Writer.Write 返回错误，这个错误就会由 TeeReader 的 Read 返回。

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

结论：TeeReader 没有内部缓冲，写端写完之前本次读不会完成；处理返回值时要先使用已经读到的 n 个字节，再根据 err 判断是否由写端失败中断。

先把 TeeReader 的错误方向画清楚

调用 io.TeeReader(r, w) 后，得到的仍然是一个 io.Reader。调用方只会调用这个 Reader 的 Read，TeeReader 在内部先从上游读取一段数据，再把这段数据交给 w.Write。因此错误出口仍然是读取接口，而不是额外暴露一个“旁路写入错误”的返回值。

这也解释了三个常见现象：

• 旁路写入很慢时，读取方会一起等待，因为 TeeReader 不替你排队。
• 旁路写入失败时，调用方应该检查 Read 的错误，而不是等待另一个异步错误通道。
• 如果某次读取已经得到 n > 0，即使同时得到非空错误，也不能直接丢掉这 n 个字节。

用一个小项目固定复现写端错误

为了看清错误从哪里来，我们做一个极小的“读取并复制”工具。写端在收到两次数据后故意返回一个可识别错误，主循环只把 TeeReader 当成普通 Reader 使用。

package main

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

var errMirrorFull = errors.New("旁路写入空间不足")

// failAfterWriter 记录写入次数，并在达到上限后返回稳定的根因。
type failAfterWriter struct {
    calls int
    limit int
}

func (w *failAfterWriter) Write(p []byte) (int, error) {
    w.calls++
    if w.calls > w.limit {
        // 返回 0 表示这次写入没有被接受，错误会由 TeeReader 交给 Read。
        return 0, errMirrorFull
    }
    return len(p), nil
}

func main() {
    src := strings.NewReader("alpha-beta-gamma")
    mirror := &failAfterWriter{limit: 2}
    reader := io.TeeReader(src, mirror)
    buf := make([]byte, 5)

    for {
        n, err := reader.Read(buf)
        if n > 0 {
            // 先消费已经成功读到的字节，不能因 err 非空而丢弃它们。
            fmt.Printf("收到 %q\n", buf[:n])
        }
        if err != nil {
            // 用 errors.Is 保留对底层写端根因的判断能力。
            fmt.Printf("读取结束: %v, isMirrorFull=%v\n", err, errors.Is(err, errMirrorFull))
            break
        }
    }
}

这个示例的关键不在于模拟一个真实磁盘，而在于让写端错误可控。failAfterWriter 满足 io.Writer 接口，TeeReader 不需要知道它是不是文件、网络连接或内存缓冲区。

为什么写端错误会从 Read 返回

io.Reader 的接口只有 Read(p []byte) (n int, err error)。TeeReader 选择在一次 Read 中同步完成旁路写入，才能保证“调用方读到的内容”与“写端收到的内容”对应。如果写端失败却仍然返回 nil，调用方会误以为复制已经成功。

因此，TeeReader 的语义可以浓缩成一条关系：上游提供数据，写端必须接收同一段数据，任意写入错误都会成为本次读取的错误。它不是 io.MultiWriter 的替代品，也不会把错误保存到某个可以稍后查询的字段中。

处理 n 和 err 时先保留有效数据

很多读取循环只写成“只要 err != nil 就退出”，这会漏掉最后一段已经读入缓冲区的数据。更稳妥的顺序是先处理 n > 0，再处理错误。

func consume(r io.Reader, handle func([]byte) error) error {
    buf := make([]byte, 32)
    for {
        n, err := r.Read(buf)
        if n > 0 {
            // 先处理本次已经交付的字节，避免与错误一起返回时丢数据。
            if handleErr := handle(buf[:n]); handleErr != nil {
                return fmt.Errorf("处理已读数据: %w", handleErr)
            }
        }
        if err != nil {
            // EOF 是正常结束；其它错误要原样向上返回。
            if errors.Is(err, io.EOF) {
                return nil
            }
            return fmt.Errorf("读取或旁路写入失败: %w", err)
        }
    }
}

这里的 handle 可以是写文件、计算摘要或更新统计数据的函数。示例没有把代码运行结果伪装成截图；真正接入时，调用方可以根据自己的业务决定如何记录处理失败。

错误包装后怎样判断真正的写端根因

工程代码通常会给错误增加上下文，例如“读取上传内容失败”。如果想让上层仍能判断是不是旁路写端错误，应使用 %w 包装，并在上层使用 errors.Is 或 errors.As。

func readWithMirror(src io.Reader, dst io.Writer) error {
    reader := io.TeeReader(src, dst)
    _, err := io.Copy(io.Discard, reader)
    if err != nil {
        // %w 保留 TeeReader 返回的底层错误，便于上层分类处理。
        return fmt.Errorf("读取并复制输入失败: %w", err)
    }
    return nil
}

func isMirrorCapacityError(err error) bool {
    // 通过 errors.Is 穿过业务上下文，判断写端是否返回了目标根因。
    return errors.Is(err, errMirrorFull)
}

不要仅依赖错误字符串包含“写入失败”。字符串适合日志阅读，不适合作为稳定的分支条件；可比较的哨兵错误或自定义错误类型更容易跨函数传递。

什么时候应该换一种设计

TeeReader 很简洁，但它的同步语义决定了适用边界。下面几种情况要谨慎：

尤其不要把“没有内部缓冲”理解成“数据一定已经落盘”。TeeReader 只负责调用 Writer 的 Write；底层 Writer 是否还有自己的缓存、何时持久化，仍由 Writer 的实现决定。

最后记住这三个检查点

1. 把 TeeReader 当成同步的 Reader：每次 Read 都可能触发一次对应的 Write。
2. 处理返回值时先处理 n > 0，再判断 err，不要因为错误丢掉已经读到的数据。
3. 需要区分写端根因时，用可比较的错误值或类型，并通过 %w 和 errors.Is 传递判断能力。

相关问题

TeeReader 会把数据缓存起来等写端慢慢处理吗？

不会。官方语义是没有内部缓冲，写端完成前这次读取不会完成。

写端返回错误时，已经读到的 n 个字节还有效吗？

如果 n > 0，调用方应先按自己的协议处理这部分数据，再处理错误；不要只看错误就丢弃缓冲区前缀。

能否从 TeeReader 单独取出写端错误？

标准 TeeReader 不提供第二个错误通道，写端错误通过 Read 返回。若业务需要独立统计，就要在 Writer 或外层包装器中自行记录。