Go iter.Pull2 怎么区分迭代结束和迭代器返回的错误值

使用 iter.Pull2 时，最容易混淆的是把第二个值里的 error 当成了迭代结束信号。正确判断顺序是：先看第三个返回值 valid，只有 valid == false 才表示序列结束；当 valid == true 时，第二个值即使是非 nil 错误，也仍然是一个有效的迭代结果。

官方地址：https://pkg.go.dev/iter#Pull2

这条规则对把流式读取、批处理或目录扫描改造成 Seq2[K, V] 的代码尤其重要。Pull2 不会额外返回一个“迭代器错误”通道，错误是否出现，取决于你的 V 类型和迭代器约定。

升级范围：Pull2 把 Seq2 转成逐项读取

Go 的 iter.Seq2[K, V] 是一个向回调函数推送成对值的函数类型。iter.Pull2 把它转换成两个函数：next 每次拉取一个 pair，stop 负责结束消费。它的签名可以概括为：

next() (K, V, bool)
stop()

这里的布尔值不是“错误是否存在”，而是“这次返回的 pair 是否有效”。自然结束时，next 返回 K 和 V 的零值，同时返回 false。因此，V 恰好是 error 时，错误值和结束标记是两个完全不同的维度。

变更表：三个返回位置各自负责什么

例如，("worker-7", io.ErrUnexpectedEOF, true) 表示当前确实拉取到了一个 pair，只是这个 pair 携带了错误；("", nil, false) 才表示没有下一个 pair。不要通过比较键或错误值的零值来猜测是否结束。

旧代码风险：把非 nil error 直接当成结束

从普通的“读取函数返回 value 和 error”迁移过来时，常见误写是先判断错误，再判断 valid。这种写法会把“有效 pair 携带业务错误”和“序列已经结束”混在一起，也可能跳过键值中用于定位错误来源的信息。

// 错误值是序列中的 V，不能用它代替 valid 判断结束。
for {
	key, errValue, valid := next()
	if !valid {
		// 只有 valid 为 false，才是自然结束。
		break
	}
	if errValue != nil {
		// valid 为 true，说明 key 和 errValue 属于一个有效 pair。
		return fmt.Errorf("读取 %s 失败: %w", key, errValue)
	}
	// 这里才处理没有错误的有效结果。
	fmt.Println("读取成功:", key)
}

这个判断顺序的核心不是语法习惯，而是数据模型：valid 描述迭代器状态，errValue 描述当前元素的业务内容。两者不能互相替代。

新写法：让错误值和结束状态分开处理

下面构造一个很小的 Seq2[string, error]。它先返回一个成功项，再返回一个带错误的有效项，最后自然返回。消费方会在遇到错误项时退出，因此最后的自然结束不会被拉取到。

package main

import (
	"errors"
	"fmt"

	"iter"
)

func records() iter.Seq2[string, error] {
	return func(yield func(string, error) bool) {
		// 第一个 pair 表示成功读取到一个记录。
		if !yield("config.yaml", nil) {
			return
		}
		// 第二个 pair 仍然有效，只是把错误作为 V 传给调用方。
		yield("worker-7", errors.New("读取分片失败"))
	}
}

func consume(seq iter.Seq2[string, error]) error {
	next, stop := iter.Pull2(seq)
	// 提前遇到错误时也要停止底层迭代器。
	defer stop()

	for {
		key, errValue, valid := next()
		if !valid {
			// 只有这里表示所有 pair 都已经消费完。
			return nil
		}
		if errValue != nil {
			// 这是有效 pair 携带的业务错误，不是迭代结束。
			return fmt.Errorf("处理 %s 失败: %w", key, errValue)
		}
		fmt.Println("处理成功:", key)
	}
}

func main() {
	// 示例会先打印成功记录，然后返回 worker-7 的错误。
	if err := consume(records()); err != nil {
		fmt.Println(err)
	}
}

这段代码里，worker-7 对应的 valid 仍然是 true。如果把 if errValue != nil 写成“结束”，表面上结果可能看起来一样，但调用方会失去“这是哪个键产生的错误”这一层语义，也无法区分错误项和真正的序列耗尽。

回归检查：自然结束和提前退出都要收尾

Pull2 的 stop 不是可有可无的附加函数。官方文档要求调用方在不再需要后续值、且还没有收到 valid=false 时调用它；最稳妥的写法是在拿到 next 后立即 defer stop()。这样，错误分支、业务筛选分支或上层取消分支都能释放底层迭代器。

// 只取前两个有效 pair 时，提前 return 也必须触发 stop。
func takeTwo[K any, V any](seq iter.Seq2[K, V]) {
	next, stop := iter.Pull2(seq)
	defer stop()

	for i := 0; i 

如果循环完整消费到 valid=false，再次调用 stop 也是允许的；因此统一使用 defer stop() 可以减少分支遗漏。next 和 stop 也不应被多个 goroutine 同时调用，迁移时不要把同一组函数随意分发给并发消费者。

迁移清单：把判断顺序固定下来

1. 先确认 V 的真实类型；如果是 error，错误就是第二个返回值。
2. 每次调用 next 后先判断 valid，为 false 时结束读取。
3. 只有 valid 为 true，才读取键和值的业务含义。
4. 有效值中的非 nil 错误按业务错误处理，不把它改写成“没有更多数据”。
5. 拿到 next 后立即注册 defer stop()，覆盖自然结束和提前退出。

可以把 Pull2 的消费模板记成一句话：先判 valid，再判 error；先注册 stop，再决定何时 return。

相关问题

Pull2 结束时第二个值一定是 nil 吗？

如果 V 是 error，自然结束时会返回 error 的零值，也就是 nil；但真正表示结束的是第三个返回值 false，不要只检查 nil。

错误值为 nil 且 valid 为 false，能当作一条空记录吗？

不能。valid=false 表示当前没有有效 pair，第一、第二个值只是各自类型的零值，不能当作业务记录使用。

已经收到 valid=false 还需要调用 stop 吗？

可以继续调用，文档允许在已经结束后调用 stop。统一保留 defer stop() 更容易覆盖所有提前退出路径。