iter.Pull2 读取双值迭代器时的关闭与错误顺序

使用 iter.Pull2 时，稳妥顺序是：拿到 next 和 stop 后立即 defer stop() 兜底；如果要读取生产者维护的终态错误，循环结束后再显式调用一次 stop()，确认生产者已经返回，最后读取 Err()。官方允许重复调用 stop，所以“defer 兜底 + 显式完成”不会冲突。

Go iter 官方文档：https://pkg.go.dev/iter

最小可用写法

next, stop := iter.Pull2(source.Seq())
defer stop() // 任何提前 return 或 panic 路径都能通知生产者停止。

for {
	key, value, ok := next()
	if !ok {
		break // 自然结束时，生产者已经返回。
	}
	if wanted(key) {
		fmt.Println(key, value)
		break // 提前停止，后面要显式完成生产者。
	}
}

stop() // 允许重复调用；此处确保生产者的 defer 已执行。
if err := source.Err(); err != nil {
	return err // 最后读取扫描、解析或关闭阶段留下的错误。
}

next() 返回的布尔值只说明这一对值是否有效，不是业务错误位。序列结束或调用 stop() 后，再调用 next() 会持续得到两个零值和 false。如果迭代器内部 panic，调用 next 或 stop 的一方也会收到同一个 panic。

真正需要保护的不是 stop 本身

把 Pull2 放进资源型迭代器时，需要保护四个对象：底层文件或响应体、生产者是否已经返回、生产者最终写入的错误状态，以及调用方是否可能提前离开。stop 是让这些对象完成收尾的控制点，不是一个可选的“优化调用”。

官方要求：如果调用方没有把序列消费到 ok == false，就必须调用 stop，让迭代函数能够结束返回。常规写法是立刻 defer stop()，这样错误返回、条件分支和 panic 都不会漏掉清理。

三个最常见的风险入口

提前 break，却没有 stop

调用方拿到目标键值后直接返回，生产者可能还停在一次交付上，内部资源的 defer 也没有机会及时执行。即使当前迭代器底层只是内存，将来换成文件、数据库游标或网络响应时也会留下隐患。

只 defer stop，却过早读取 Err

defer stop() 要到当前函数返回时才执行。如果代码在 return 之前先调用 source.Err()，生产者的收尾逻辑可能尚未设置扫描错误或关闭错误。此时读到 nil，并不一定代表整个生产过程没有错误。

多个 goroutine 同时调用 next 或 stop

官方文档明确说明，不允许从多个 goroutine 同时调用 next 或 stop。Pull2 是单消费者控制接口；若需要并行处理，先在一个 goroutine 中拉取，再把已经取得的值交给受控工作队列，不要共享这两个函数。

一个可关闭、可查错的双值源

下面的 PairSource 从 io.ReadCloser 读取 key=value。它是单次迭代器：解析错误、扫描错误和关闭错误都由生产者保存，调用方在完成 stop 后读取。

package pairs

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

type PairSource struct {
	input io.ReadCloser
	err   error
	used  bool
}

func New(input io.ReadCloser) *PairSource {
	return &PairSource{input: input}
}

func (s *PairSource) Seq() iter.Seq2[string, string] {
	return func(yield func(string, string) bool) {
		if s.used {
			return // 资源流不可回放，第二次调用不再产出数据。
		}
		s.used = true

		scanner := bufio.NewScanner(s.input)
		defer func() {
			// 收尾错误要在生产者退出前合并，Err 才能看到最终状态。
			s.err = errors.Join(s.err, scanner.Err(), s.input.Close())
		}()

		lineNo := 0
		for scanner.Scan() {
			lineNo++
			key, value, ok := strings.Cut(scanner.Text(), "=")
			if !ok || key == "" {
				s.err = fmt.Errorf("第 %d 行不是 key=value", lineNo)
				return
			}
			if !yield(key, value) {
				return // stop 会让 yield 返回 false，随后执行 defer 清理。
			}
		}
	}
}

func (s *PairSource) Err() error {
	return s.err // 仅在消费端完成 stop 后读取。
}

这个示例没有给 PairSource 加锁，因为它的契约就是单次、单消费者。若业务必须跨 goroutine 查询状态，应重新设计所有权，不要只给 Err 加锁后就把 next 和 stop 暴露给并发调用。

错误顺序为什么必须放在关闭之后

错误来源可以分成三类：解析错误在生产者循环中产生；扫描错误通常在读取结束时由 Scanner.Err() 给出；关闭错误要到 Close() 执行后才能确定。只要其中任何一种是在生产者的 defer 中合并，调用方就必须先让生产者返回。

自然消费到 ok == false 时，生产者已经完成，随后调用 stop 仍然合法。提前停止时，显式 stop 负责推进到同一个完成状态；等它返回后再读 Err，错误信息才完整。

调用方完整示例

func findPair(src *pairs.PairSource, target string) (string, error) {
	next, stop := iter.Pull2(src.Seq())
	defer stop() // 所有异常退出路径的兜底。

	var found string
	for {
		key, value, ok := next()
		if !ok {
			break
		}
		if key == target {
			found = value
			break // 找到目标后不再消费剩余输入。
		}
	}

	stop() // 先让生产者完成扫描收尾与输入关闭。
	if err := src.Err(); err != nil {
		return "", err
	}
	return found, nil
}

风险和控制速查

验证清单

• next, stop := iter.Pull2(seq) 后是否立刻写了 defer stop()。
• 所有提前 break、return 和 panic 路径是否都能触发 stop。
• 终态 Err() 是否在显式 stop 之后读取。
• 生产者是否在 yield 返回 false 后立即返回，不再继续调用 yield。
• 是否避免多个 goroutine 同时调用 next 或 stop。
• 资源型序列是否明确记录为单次迭代器。

小结

iter.Pull2 的关闭规则可以记成一句话：defer stop 保证一定关闭，显式 stop 保证现在完成，Err 放在完成之后读取。ok 只负责键值对是否有效，业务错误需要由迭代器自己的错误契约承载。把资源所有权和单消费者边界写清楚，提前退出就不会变成漏清理或漏报错。