Go io.TeeReader 写入失败为什么表现为读取错误

Go 里 io.TeeReader 的旁路写入失败，通常不会从 Write 调用点直接冒出来，而是出现在下一次读取返回值里。这不是错误归属错了，而是 TeeReader 本身只实现了 io.Reader：它先从源读取，再同步把读到的字节交给旁路 Writer，最后只能通过 Read(p) 的 err 把写入结果交还给调用者。

io.TeeReader 的调用链决定了错误出口

io.TeeReader(r, w) 返回的仍然是一个 Reader。调用它的 Read 时，内部先调用源 Reader 的 Read，如果拿到了字节，就立即调用 w.Write。这里没有异步队列，也没有“先把数据交给主流程、稍后再写”的阶段，因此旁路写入的耗时和错误都会影响当前读取。

这类组合常见于请求体复制、上传内容计算摘要、调试审计或把输入同时写入缓存。下面的结构图只表达函数与数据关系，不是运行截图。

package main

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

func main() {
	// 源数据只读取一次，同时把读到的字节复制到旁路缓冲区。
	source := strings.NewReader("request-body")
	var audit bytes.Buffer
	tee := io.TeeReader(source, &audit)

	body, err := io.ReadAll(tee)
	// 读取错误必须保留；成功时 body 与 audit 应包含同一段数据。
	fmt.Printf("body=%q audit=%q err=%v\n", body, audit.String(), err)
}

旁路 Writer 失败时，为什么看起来像 Reader 失败

关键在于 TeeReader 的实现返回值。源 Reader 先返回一段数据后，TeeReader 调用 Writer；如果 Writer 返回错误，TeeReader 直接把 Writer 的返回值和错误交给上层。于是上层看到的是“读操作失败”，但真正的故障点可能是磁盘空间、网络连接、哈希包装器或 io.MultiWriter 中的某个分支。

下面的 Writer 故意拒绝第一段数据。它用来观察错误路径，代码中的输出是示意结果，不把未执行的结果当作运行证据。

package main

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

var errAuditSink = errors.New("audit sink is unavailable")

type failingWriter struct{}

func (failingWriter) Write(p []byte) (int, error) {
	// 模拟旁路存储不可用；返回 0 表示本次没有接受任何字节。
	return 0, errAuditSink
}

func main() {
	tee := io.TeeReader(strings.NewReader("payload"), failingWriter{})
	data, err := io.ReadAll(tee)
	// 错误从 Read 暴露，调用者应记录旁路故障而不是误判源数据损坏。
	fmt.Printf("data=%q err=%v\n", data, err)
}

还要注意一个容易忽略的细节：TeeReader 的写错分支会返回 Writer 的 n。如果 Writer 返回 0, errAuditSink，这次 Read 对调用者就是 n == 0 和非空错误，源 Reader 在内部读到的那段字节已经不能靠下一次 Read 重新取回。因此旁路 Writer 如果只接受部分数据，必须同时返回清晰的非 nil 错误，让上层决定是否丢弃、重放或终止。

处理 Read 返回值：先保留数据，再判断错误

普通 Reader 的通用约定是：如果 n > 0，即使同时有错误，也应先处理这部分数据。手动循环可以按下面的顺序写；对 TeeReader 来说，写入错误出现时尤其不能只打印“读取失败”就继续循环，因为源数据可能已经被消费。

buf := make([]byte, 32*1024)
for {
	n, err := tee.Read(buf)
	if n > 0 {
		// 先消费当前确实返回的字节，避免丢掉合法的部分结果。
		if _, writeErr := destination.Write(buf[:n]); writeErr != nil {
			return fmt.Errorf("保存读取内容失败: %w", writeErr)
		}
	}
	if err != nil {
		// EOF 是正常结束，其它错误应保留原始原因并停止重试。
		if !errors.Is(err, io.EOF) {
			return fmt.Errorf("读取或旁路写入失败: %w", err)
		}
		break
	}
}

如果使用 io.ReadAll 或 io.Copy，它们会把 Read 错误作为返回错误交给调用者。此时要把已经返回的部分数据和错误一起纳入事务设计：可重放的源可以重新建立 TeeReader；不可回退的网络流则更适合先写入可靠的本地暂存，再异步做审计。

旁路 Writer 的选择与排查清单

内存中的 bytes.Buffer 和哈希实现通常只会在资源问题或自定义包装器中失败；文件、网络连接和 io.MultiWriter 则应把错误视为主流程的一部分。io.MultiWriter 的任一分支失败，都可能让 TeeReader 的 Read 提前返回，所以需要记录哪个分支先失败，不能只看“读取错误”四个字。

排查时按这四项走：确认源 Reader 是否真的返回数据；给旁路 Writer 保留带上下文的错误；检查是否出现部分写入；最后确认业务是否允许从源头重放。若目标是异步审计，不要把一个网络 Writer 直接塞进 TeeReader 期待它自动缓冲，应显式设计有界队列、背压和失败落盘。

常见问题

io.TeeReader 会把数据缓存起来吗？

不会。它没有内部缓冲，旁路 Write 完成前本次 Read 不会完成；需要异步化时应另行设计缓冲队列。

为什么错误堆栈里只有 Read？

因为上层拿到的是 TeeReader 暴露的 Reader 接口。应沿着错误链检查旁路 Writer 返回的原始错误，并在包装时保留上下文。

Writer 返回短写但没有错误怎么办？

这是不符合常规 Writer 契约的实现，应修正或用包装器把短写转换为明确错误；不要把旁路副本当成完整副本。