iter.Seq2 组合键值流的收集与错误传递

iter.Seq2[K, V] 很适合表达惰性的键值流，但它一次只能向消费者交付两个值。只要业务还要返回读取、解析或远程调用错误，就不能把 maps.Collect 当成完整答案。工程上通常有三种契约：把错误包进值、在迭代结束后查询终态错误，或者直接返回 map[K]V, error。选择标准不是代码最短，而是是否允许部分结果、是否需要惰性，以及调用方能否可靠检查终态。

官方资料：https://pkg.go.dev/iter、https://pkg.go.dev/maps、https://go.dev/blog/range-functions

无错误来源直接用 maps.Collect

Go 官方把 Seq2 定义为成对值的迭代器，常见含义就是键值或索引值。来源不会失败时，直接收集最清楚：

package main

import "maps"

func clone[K comparable, V any](src map[K]V) map[K]V {
	// maps.All 生成键值流，Collect 将它物化为新 map。
	return maps.Collect(maps.All(src))
}

maps.Collect 的返回值只有 map[K]V，所以它适合“流本身没有可报告错误”的情况。如果生产者在中途因为错误直接返回，调用方得到的只是一个看似正常的部分 map，无法区分“自然结束”和“失败结束”。

Seq2 为什么没有第三个 error 位置

Seq2[K,V] 的签名等价于 func(yield func(K,V) bool)。两个输出位已经被键和值占用；yield 的布尔返回值只表示消费者是否还要继续，并不表示生产者是否成功。

因此不要把错误偷偷塞进零值，也不要依靠 panic 传递普通业务失败。更可靠的做法是把错误设计成类型契约，并让消费者能明确地处理。

三种错误传递方案怎么选

把错误包进值

把第二个类型参数改成 Result[V]，每次产出都能携带值或错误：

package stream

import "iter"

type Result[V any] struct {
	Value V
	Err   error
}

func CollectResult[K comparable, V any](
	seq iter.Seq2[K, Result[V]],
) (map[K]V, error) {
	out := make(map[K]V)

	for key, item := range seq {
		if item.Err != nil {
			// 原子语义：发生错误时丢弃已经收集的部分结果。
			return nil, item.Err
		}
		out[key] = item.Value
	}

	return out, nil
}

这个方案的优势是错误就出现在数据流中，适配器不需要额外状态；缺点是标准 maps.Collect 不能直接使用，所有消费者都要理解 Result。它适合边读边解析、错误可能出现在任意元素位置的流。

如果业务允许保留部分结果，只需在错误分支返回 out, item.Err。但函数名或注释必须写清“错误时 map 仍可用”，否则调用方很容易把不完整数据当成完整数据。

迭代结束后查询终态错误

生产者仍返回 iter.Seq2[K,V]，同时提供 Err() error 或错误查询闭包。这个接口接近 bufio.Scanner 的使用习惯，调用方必须在循环结束后检查错误。

这种设计能保持标准键值流类型，但约束更重：终态错误属于一次迭代，通常意味着流是单次使用的；若消费者提前停止，还要区分“主动停止”和“来源失败”。忘记调用 Err() 也会把失败误判为正常结束。因此它只适合团队能够统一消费模板、且需要兼容现有 Seq2[K,V] 适配器的场景。

立即物化为 map 和 error

当数据量有界、调用方最终一定需要完整 map，而且任何错误都应让整批结果失效时，直接返回 (map[K]V, error) 最简单。它牺牲惰性，却换来最明确的原子性，调用方也不会漏查终态错误。

生成一个带错误的键值流

下面把多行 key=value 文本解析为单次键值流。格式错误作为 Result 进入流；消费者返回 false 后，生产者立即停止。

package stream

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

func ParsePairs(text string) iter.Seq2[string, Result[string]] {
	return func(yield func(string, Result[string]) bool) {
		scanner := bufio.NewScanner(strings.NewReader(text))
		lineNo := 0

		for scanner.Scan() {
			lineNo++
			key, value, ok := strings.Cut(scanner.Text(), "=")
			if !ok || key == "" {
				// 错误占据值包装，不伪装成正常零值。
				yield("", Result[string]{
					Err: fmt.Errorf("第 %d 行不是 key=value", lineNo),
				})
				return
			}

			if !yield(key, Result[string]{Value: value}) {
				// 消费者主动停止时，不再读取后续输入。
				return
			}
		}

		if err := scanner.Err(); err != nil {
			// 扫描器的终态错误同样进入 Result 契约。
			yield("", Result[string]{Err: err})
		}
	}
}

调用方可以用同一个收集器获得全有或全无的结果：

package main

import (
	"fmt"
	"log"
)

func main() {
	seq := stream.ParsePairs("host=127.0.0.1\nport=8080")
	values, err := stream.CollectResult(seq)
	if err != nil {
		// 收集失败时不使用部分 map。
		log.Fatal(err)
	}

	fmt.Println(values["host"])
}

提前停止和 Pull2 的边界

直接 for range 时，循环提前 break 会让 yield 返回 false，生产者必须立即返回并执行自己的 defer 清理。如果改用 iter.Pull2 手动拉取，且没有把序列消费到 ok == false，调用方必须执行 stop()：

next, stop := iter.Pull2(seq)
defer stop() // 提前结束时也让生产者完成清理。

key, item, ok := next()
if ok && item.Err == nil {
	fmt.Println(key, item.Value)
}

不要从多个 goroutine 同时调用 next 或 stop。对于文件、数据库游标或网络响应一类资源，把关闭逻辑放在迭代器内部的 defer 中，并让 stop() 有机会触发它。

决策表

常见错误

• 用空键或零值表示失败：正常数据可能同样是零值，语义不可区分。
• 生产者出错后直接返回：消费者会把部分 map 当成完整结果。
• 错误时既 yield 错误又继续产出：收集器的终止规则变得不确定。
• 暴露 Err() 却不说明单次使用：第二次迭代可能读到旧错误或空流。
• 使用 Pull2 提前退出却不调用 stop()：生产者可能无法及时清理资源。

小结

iter.Seq2 解决的是两个值如何惰性传递，不负责替业务定义错误通道。无错误来源直接配合 maps.Collect；需要逐元素报告失败时，用 Result[V] 并通过专用收集器决定原子或部分语义；若数据量有界且必须全有或全无，直接返回 map,error 更清楚。无论选择哪种方案，都要把提前停止、单次使用和资源释放写进契约。