Go iter.Seq2 双值迭代器的 range 消费方式

拿到 iter.Seq2[K, V] 时，最直接的消费方式就是写两个 range 变量：for key, value := range seq2。第一个变量接收 yield 的第一个参数，第二个变量接收第二个参数；如果只需要其中一个，就用 _ 明确丢弃另一个。它不是返回键值对的普通函数，而是 Go 1.23 支持的双值推送迭代器。

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

把 Seq2 看成“生产者反复调用 yield(key, value)，range 负责接收”的协议，就不容易把它误写成 pull 迭代器，也能正确处理提前退出。

先认出 Seq2 是一对值的推送迭代器

iter.Seq2[K, V] 的本质是一个函数类型：它接收 func(K, V) bool 形式的 yield 函数。迭代器每产生一组数据，就调用一次 yield；range 循环把这两个参数映射到左侧的两个变量。这个方向很重要：业务代码是在消费被推送的键和值，而不是主动调用 next 函数。

package main

import (
	"fmt"
	"iter"
)

// pairs 返回一个双值迭代器：每次把编号和名称交给 yield。
func pairs() iter.Seq2[int, string] {
	return func(yield func(int, string) bool) {
		items := []string{"alpha", "beta", "gamma"}
		for id, name := range items {
			// yield 返回 false 表示调用方已经不再需要后续数据。
			if !yield(id+1, name) {
				return
			}
		}
	}
}

func main() {
	// 左边两个变量依次接收 key 和 value。
	for id, name := range pairs() {
		fmt.Println(id, name)
	}
}

上例中，id 对应 yield 的第一个参数，name 对应第二个参数。Go 语言规范允许函数型 range 最多产生两个迭代值，所以 for id, name := range pairs() 是 Seq2 最清晰的写法。

用两个变量接住键和值

消费端是否需要两个值，决定 range 左侧的写法。如果要同时处理键和值，就使用两个变量；如果只关心值，可以写成 for _, value := range seq2；如果只关心键，则写成 for key := range seq2。单变量写法只保留第一个迭代值，并不会自动把第二个值打包成结构体。

// 只关心值：第一个参数用空白标识符丢弃。
for _, value := range seq2 {
	consume(value)
}

// 只关心键：只声明一个迭代变量即可。
for key := range seq2 {
	logKey(key)
}

因此，看到“值为空”时先检查变量顺序和数量：生成器到底调用的是 yield(key, value) 还是 yield(value, key)，消费端是否错误地只保留了第一个值。对 maps.All(m) 这类键值迭代器，最稳妥的表达通常是 for key, value := range maps.All(m)，不要依赖变量名猜含义。

这个模式的适用压力是“不同容器都能提供同一种键值序列”。输入可以来自 map，也可以来自树、分页读取器或自定义索引；只要对外返回标准的 iter.Seq2[K, V]，消费方就能保持同一套 range 代码。

提前 break 时要让迭代器收尾

range 循环提前 break、return 或因为其他控制流离开时，运行时会让 yield 返回 false，迭代器应当据此停止生产并完成清理。自定义 Seq2 不能忽略这个返回值，否则读者以为已经停止，生产者却可能继续准备数据或持有资源。

func firstMatch(seq2 iter.Seq2[int, string], want string) (int, bool) {
	var found int
	// range 提前结束时，Seq2 应收到停止信号并返回。
	for id, name := range seq2 {
		if name == want {
			found = id
			break
		}
	}
	return found, found != 0
}

迭代器内部应把 yield 的 false 当作边界，而不是当作普通业务值继续向下走。对只消费一次的流式迭代器，这个细节尤其关键：提前退出时要关闭文件、停止 goroutine 或释放临时状态。range 的好处是它替消费方完成了停止信号传递。

需要逐个拉取时再切换到 iter.Pull

Seq2 的默认消费模型是 push：生产者调用 yield，range 接住结果。如果业务必须把两个迭代器并行比较、逐个决定下一步，才考虑 iter.Pull2 或相应的 pull API。不要为了“看起来更底层”把所有 Seq2 都改成 next 循环；简单遍历用 range 更容易表达停止边界。

// 把 Seq2 收集成 map，交给标准库适配器完成消费。
func collectPairs(seq2 iter.Seq2[string, int]) map[string]int {
	result := make(map[string]int)
	for key, value := range seq2 {
		// 明确地把当前键和值写入新的结果对象。
		result[key] = value
	}
	return result
}

判断清单可以压缩成四点：第一，确认项目使用的 Go 版本支持函数型 range；第二，确认 Seq2 的 yield 参数顺序；第三，按需写两个、一个或带 _ 的变量；第四，检查迭代器收到 false 后是否能收尾。满足这四点，绝大多数“Seq2 怎么 range”问题都能定位。

常见问题

Seq2 能不能写成一个变量接收两个值？

不能把两个值自动打包成一个变量。一个变量只接收第一个迭代值；需要键和值时必须声明两个变量，或者让迭代器本身返回一个结构体并改用 iter.Seq[T]。

为什么 break 后自定义迭代器还在工作？

通常是迭代器忽略了 yield 的 false 返回值。生产循环应在 false 时立即 return，并把关闭资源或停止后台工作的逻辑放在这个收尾路径上。

map 的 Seq2 顺序稳定吗？

不要从 iter.Seq2 推断顺序稳定性。若来源是 map，应按 map 的遍历语义处理；需要稳定结果时先定义排序或使用能表达顺序的上游数据结构。

记住一句话就够了：Seq2 把两个值通过 yield 推给 range，左侧变量按参数顺序接收；提前离开循环时，迭代器必须尊重停止信号并完成清理。