Go io.TeeReader 为什么读取时才会报告写端错误

我第一次把 io.TeeReader 接到请求体审计流时，最容易误判的一点是：明明是 Writer 写失败，错误却出现在下一次 Read 的返回值里。结论其实很直接：TeeReader 只有在调用方读取时才会同时向 Writer 写入；Writer 的失败会按 Reader 的错误返回给调用方。它不是后台复制器，也没有把写端错误单独保存成另一条通知。

io.TeeReader 的接口目标是“读一次，同时写一次”

io.TeeReader(r, w) 返回的类型仍然是 io.Reader。这决定了调用方看到的入口只有 Read(p)，而不是一个额外的“复制完成”接口。官方文档明确说明：从包装器读取的数据会写入 w，并且没有内部缓冲，写入必须在读取完成前结束。

这是一种调用方体验上的取舍：上层仍可把它交给 io.ReadAll、io.Copy 或解析器，但复制动作的进度和失败都被绑定在这些读取动作上。没有发生读取，就没有需要报告的写入结果。

package main

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

func mirrorOnce() error {
	// src 是输入流，mirror 接收每次 Read 读出的同一段字节。
	src := strings.NewReader("request-body")
	var mirror bytes.Buffer
	tee := io.TeeReader(src, &mirror)

	buf := make([]byte, 5)
	for {
		n, err := tee.Read(buf)
		// n 与 err 需要同时判断，因为一次 Read 可能先返回数据再返回错误。
		if n > 0 {
			fmt.Printf("read=%q mirror=%q\\n", buf[:n], mirror.String())
		}
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return fmt.Errorf("读取并镜像失败: %w", err)
		}
	}
}

这里的 mirrorOnce 没有主动调用 Writer。调用 tee.Read 时，包装器才把同一段数据送到 mirror。因此判断错误时不能只写成“n == 0 才处理错误”，也不能只看输入 Reader 是否返回了错误。

为什么写端错误会像读取失败一样出现

可以把一次 Read 看成一个接口契约：调用方请求数据，TeeReader 从底层 Reader 获取数据，再把这段数据交给 Writer；只有写端动作完成后，包装器才决定这次 Read 返回什么。写端返回错误时，最符合 Reader 抽象的做法就是把它作为本次 Read 的错误交给调用方。

所以“延迟”只是观察位置上的延迟，不是错误被吞掉后很久才异步出现。错误发生在读取链路的同步复制阶段，调用方只是在 Read 返回时收到它。TeeReader 也不会替 Writer 重试、缓存失败数据或另起 goroutine。

type failWriter struct {
	limit int
	wrote int
}

func (w *failWriter) Write(p []byte) (int, error) {
	// 只接受 limit 以内的数据，用于说明写端失败如何回到 Read。
	remain := w.limit - w.wrote
	if remain  remain {
		w.wrote += remain
		return remain, io.ErrShortWrite
	}
	w.wrote += len(p)
	return len(p), nil
}

func readWithFailWriter() error {
	// TeeReader 的返回值仍按 Reader 处理，写端错误不会从另一个接口返回。
	tee := io.TeeReader(strings.NewReader("abcdef"), &failWriter{limit: 3})
	data, err := io.ReadAll(tee)
	if err != nil {
		return fmt.Errorf("读取链路失败，已得到 %d 字节: %w", len(data), err)
	}
	return nil
}

这段示例里的关键不是错误文本，而是错误归属：io.ReadAll 只认识它正在消费的 Reader，所以它会把 TeeReader 报告的 Writer 错误作为读取失败返回。生产代码应保留包装后的错误上下文，方便判断是输入源失败还是镜像目标失败。

调用方应该怎样判断 n、EOF 和写入错误

处理 TeeReader 时，建议沿用普通 io.Reader 的判断顺序：先消费 n > 0 的数据，再判断 err。如果 err 是 io.EOF，通常表示输入正常结束；如果是其它错误，则说明读取链路或同步写端出现了问题。

如果镜像 Writer 是网络连接、文件或限长缓冲，还要把它的生命周期管理放在调用方。TeeReader 只负责同步地把读到的数据交给 Writer，不负责关闭 Writer，也不会把镜像结果持久化成可重放队列。

什么时候适合用，什么时候应该换思路

当主流程必须在读取时同步完成一份副本，例如计算上传摘要、把请求体写入审计文件、把响应流镜像到调试缓冲区时，TeeReader 的接口很顺手。它让上层继续使用标准 Reader 组合函数，同时把复制失败纳入同一条错误链路。

但如果镜像目标可能变慢、需要重试，或主流程不能被镜像写入阻塞，就要谨慎。官方语义是“无内部缓冲且写入完成前读取不完成”，这意味着 Writer 的速度和可用性会成为读取链路的一部分。此时应显式设计队列、背压、丢弃策略或独立的异步复制组件，而不是期待 TeeReader 在后台帮忙。

• 需要同步一致性：可以用 TeeReader，并把非 EOF 错误视为整个读取链路失败。
• 需要异步解耦：不要把慢 Writer 直接接在关键读取路径上。
• 需要重复读取：不要把 TeeReader 当成可回放缓存，它只提供当前读取过程中的一份写出。
• 需要关闭资源：由调用方分别关闭底层 Reader 和 Writer，不能把责任交给包装器。

常见问题

io.TeeReader 会不会先把数据缓存起来再写？

不会。它没有内部缓冲；每次通过包装器读取时，数据会同步写给 Writer，写入完成后这次读取才返回。

为什么我没有主动调用 Writer，却收到了写错误？

因为 TeeReader 在内部替你调用了 Writer。错误仍然属于同步复制过程，只是通过 Reader 的 Read 返回给了调用方。

读到 n 个字节时同时有错误，数据要不要丢掉？

不要机械丢弃。先按 Reader 约定处理已经返回的字节，再根据错误类型决定是否停止；对非 EOF 错误要保留上下文并定位读端或写端。