Go iotest.TimeoutReader 怎么模拟读取超时并验证重试

如果读取逻辑里有“遇到临时超时就重试”的分支，最难的通常不是写出重试，而是稳定地让测试进入这个分支。Go 标准库的 testing/iotest.TimeoutReader 正好提供了一个确定性的测试替身：它包装已有的 io.Reader，在第二次读取且没有数据时返回一次 iotest.ErrTimeout，之后再回到底层 Reader。

官方文档：https://pkg.go.dev/testing/iotest#TimeoutReader

iotest.TimeoutReader 最适合验证“调用方能否识别一次可恢复的读取超时并按上限重试”。它不模拟真实网络延迟，也不改变生产代码的超时配置。

先把 TimeoutReader 当成一种 Reader 故障注入模式

这个工具解决的是测试隔离问题：输入仍然可以来自 bytes.Reader，只是中间增加一个会按固定时机返回 ErrTimeout 的包装层。被测函数只接收 io.Reader，因此不需要知道自己读的是文件、内存还是测试替身。

这里的关键不是“制造一个慢请求”，而是制造一个明确的错误类别。因为错误出现的位置固定，测试不会受机器负载、网络状态和调度时机影响。

最小写法：让生产逻辑依赖 io.Reader

先把读取策略单独放在一个函数里。下面的实现把已读字节追加到结果中，只对 ErrTimeout 重试，且通过 maxRetries 限制次数：

package readerdemo

import (
	"errors"
	"io"

	"testing/iotest"
)

// readWithRetry 只对可恢复的读取超时重试，避免把所有错误都吞掉。
func readWithRetry(r io.Reader, maxRetries int) ([]byte, error) {
	buf := make([]byte, 4)
	var result []byte
	retries := 0

	for {
		n, err := r.Read(buf)
		if n > 0 {
			// 先保存本次已经读到的内容，再分析错误，兼容 n>0 且 err!=nil。
			result = append(result, buf[:n]...)
		}

		if err == nil {
			continue
		}
		if errors.Is(err, iotest.ErrTimeout) && retries 

这个实现体现了一个小而重要的模式：把“读取数据”和“决定是否重试”放在同一条 Reader 抽象上。业务函数不需要判断底层是 socket 还是文件，测试也能用同样的入口注入异常。

用 TimeoutReader 触发一次可预测的超时

测试输入可以很小，重点是让第一次读取拿到数据，第二次读取落入 TimeoutReader 的故障点。示例中缓冲区只有 4 字节，输入会分成多次读取；第二次读取会返回一次 ErrTimeout，下一次读取继续消费底层数据。

package readerdemo

import (
	"bytes"
	"testing"

	"testing/iotest"
)

func TestReadWithTimeoutRetry(t *testing.T) {
	// bytes.Reader 提供确定性输入，TimeoutReader 负责注入一次超时。
	reader := iotest.TimeoutReader(bytes.NewReader([]byte("golang-timeout")))

	got, err := readWithRetry(reader, 1)
	if err != nil {
		t.Fatalf("读取失败: %v", err)
	}
	if string(got) != "golang-timeout" {
		t.Fatalf("读取内容 = %q， want %q", got, "golang-timeout")
	}
}

TimeoutReader 本身没有延迟参数，也没有让测试等待某个真实时长；它按照读取次数注入错误。因此这个测试验证的是错误处理策略，而不是网络栈的计时精度。

重试策略的判断边界

读取循环里最容易出现的错误，是把所有非空错误都当作“再试一次”。这样会把权限错误、损坏数据或调用方主动取消也拖进重试。更稳妥的分流是：ErrTimeout 代表当前读取可能暂时不可用，io.EOF 代表正常结束，其他错误保持原样返回。

注意 Read 的返回值是两个维度：已经读到的字节数 n，以及本次读取的错误 err。不能因为 err 非空就丢弃 n > 0 的数据。虽然本例的注入点返回的是零字节超时，但生产实现仍然应该先处理已读字节。

表格驱动测试比单个成功用例更有价值

只写一个“超时后最终成功”的用例，还不能证明重试上限和错误分流正确。可以把正常输入、TimeoutReader 和不可恢复错误放到同一组表格中，用不同 Reader 工厂构造测试对象：

func TestReadWithRetryCases(t *testing.T) {
	tests := []struct {
		name       string
		newReader  func() io.Reader
		want       string
		wantErr    bool
	}{
		{
			name: "normal eof",
			newReader: func() io.Reader {
				return bytes.NewReader([]byte("ok"))
			},
			want: "ok",
		},
		{
			name: "timeout then success",
			newReader: func() io.Reader {
				return iotest.TimeoutReader(bytes.NewReader([]byte("retry")))
			},
			want: "retry",
		},
		{
			name: "permanent error",
			newReader: func() io.Reader {
				// ErrReader 每次都返回同一个错误，用来确认不会盲目重试。
				return iotest.ErrReader(errors.New("permanent read error"))
			},
			wantErr: true,
		},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			got, err := readWithRetry(tt.newReader(), 1)
			if (err != nil) != tt.wantErr {
				t.Fatalf("错误状态 = %v， wantErr = %v", err, tt.wantErr)
			}
			if string(got) != tt.want {
				t.Fatalf("读取内容 = %q， want %q", got, tt.want)
			}
		})
	}
}

表格里的第三个用例尤其重要：它把“重试条件必须精确匹配错误语义”固定成了回归约束。若实现后来改成遇到任意错误都重试，这个用例会直接暴露问题。

不要把这个测试替身当成真实网络超时

TimeoutReader 的优势是可预测，代价也是它过于可预测。它只在固定的读取次数上返回一次 ErrTimeout，不能证明 HTTP 客户端、TCP 连接、上下文取消或服务端负载下的时间行为。

因此可以把测试职责分成两层：

• 单元测试使用 TimeoutReader，验证 Reader 消费者的错误分类、数据保留和重试上限。
• 集成测试再使用可控的测试服务器或网络模拟，验证请求生命周期、连接复用和真实 deadline 的协作。

如果业务逻辑必须区分“可重试超时”和“用户取消”，错误类型就要在接口约定里明确；不要因为两个错误都发生在读取阶段，就把它们都包装成同一个字符串。

判断清单：什么时候应该用 TimeoutReader

• 被测函数是否只依赖 io.Reader，可以把测试替身注入进去？
• 是否只需要验证一次确定性的读取超时，而不是验证真实网络计时？
• 重试是否有明确上限，并且只匹配 iotest.ErrTimeout？
• 是否同时断言已读数据、EOF 和其他错误的处理？
• 是否把集成层的连接、deadline 和取消测试留给更高层测试？

结论

iotest.TimeoutReader 的价值不在于模拟“慢”，而在于把一个难以稳定复现的读取分支变成确定的错误输入。把它包在 bytes.Reader 外面，再让业务函数按 ErrTimeout、EOF 和其他错误分流，就能用很小的测试成本覆盖重试逻辑。

相关问题

TimeoutReader 会一直返回超时吗？

不会。官方实现是在第二次无数据读取时返回一次 ErrTimeout，后续读取继续调用底层 Reader。

可以用它测试真实 HTTP 请求超时吗？

不适合直接证明真实 HTTP 超时。它只替换一个 io.Reader，应把 HTTP 客户端的 deadline、连接和取消行为放到集成测试中。

为什么要先处理 n 再处理 err？

Reader 契约允许一次调用同时返回已读字节和错误。先处理 n > 0 可以避免在错误分支丢掉已经消费的数据。

maxRetries 应该设多大？

它应由业务允许的恢复次数决定。单元测试重点是验证边界：超时次数未超过上限时继续，超过上限后把错误交给调用方。