Go iter.Seq2 怎样把键值遍历转换成可组合迭代器

如果需要让一个自定义集合支持键值遍历，最直接的做法是返回 iter.Seq2[K, V]：它本质上是一个接收 yield func(K, V) bool 的函数。生产者每生成一组键和值就调用一次 yield，只要下游返回 false，生产者就应该立刻结束。这样，过滤、映射、截断和收集都可以继续返回另一个 iter.Seq2，形成可组合的迭代器链。

本文只围绕双值 yield、提前停止和组合调用展开。官方参考地址：https://pkg.go.dev/iter。

先看 iter.Seq2 的双值契约

iter.Seq2[K, V] 的定义可以理解为下面的函数类型：

type Seq2[K, V any] func(yield func(K, V) bool)

它与普通返回切片的函数不同：迭代器把元素推给回调，回调的布尔值承担“是否继续”的协议。返回 true 表示还要下一个键值对，返回 false 表示调用方已经得到足够结果，生产者必须停止继续调用。

在 Go 里可以直接用双变量 range 消费它：

for key, value := range seq {
	// 这里同时拿到一组键和值。
	fmt.Println(key, value)
}

如果来源是 map，还要把“能遍历”与“有固定顺序”分开。iter.Seq2 只描述键值传递方式，不会自动给 map 增加排序保证。

把键值来源封装成 Seq2

下面的适配器把一个 map 暴露为键值迭代器。关键保护点只有一个：检查 yield 的返回值，避免下游已经停止后仍继续读取和推送。

package main

import (
	"fmt"
	"iter"
)

func FromMap[K comparable, V any](src map[K]V) iter.Seq2[K, V] {
	return func(yield func(K, V) bool) {
		for key, value := range src {
			// 下游返回 false 就代表主动停止，生产者必须退出。
			if !yield(key, value) {
				return
			}
		}
	}
}

func main() {
	values := map[string]int{"go": 3, "iter": 2, "seq2": 1}
	for key, value := range FromMap(values) {
		// 这里的输出顺序不应作为业务结果的排序依据。
		fmt.Println(key, value)
	}
}

这个函数的资源边界也很清晰：调用 FromMap 只创建一个闭包，不会复制 map。闭包执行期间仍然读取原 map，因此如果多个 goroutine 同时修改 map，仍需由调用方提供同步；iter.Seq2 本身不是并发保护。

让过滤器正确转发停止信号

可组合的过滤器不应该自己重新发明遍历协议，而是接收上游 iter.Seq2，再把满足条件的键值对交给下游：

func Filter[K, V any](
	src iter.Seq2[K, V],
	keep func(K, V) bool,
) iter.Seq2[K, V] {
	return func(yield func(K, V) bool) {
		// 上游负责产生数据，本层只决定是否转发。
		src(func(key K, value V) bool {
			if !keep(key, value) {
				// true 表示继续让上游寻找下一项。
				return true
			}
			// 把下游的停止决定原样传回上游。
			return yield(key, value)
		})
	}
}

这里有两个不同的 false 场景。keep 返回 false 只是“当前元素不入选”，所以要返回 true 继续扫描；下游 yield 返回 false 才是“整条链停止”，这个结果必须原样向上游传播。

映射键值并保持组合关系

映射器可以改变键和值的类型，但仍然只做一件事：收到上游元素后生成新元素，并把下游布尔值返回给上游。

func Map[K1, V1, K2, V2 any](
	src iter.Seq2[K1, V1],
	convert func(K1, V1) (K2, V2),
) iter.Seq2[K2, V2] {
	return func(yield func(K2, V2) bool) {
		// convert 只负责转换，不负责决定整条链何时结束。
		src(func(key K1, value V1) bool {
			newKey, newValue := convert(key, value)
			// false 会沿着 src 的回调链传回最初的生产者。
			return yield(newKey, newValue)
		})
	}
}

于是可以把“map 来源 → 过滤 → 映射”写成一条链。每个函数都返回同样的迭代器形状，调用方无需先创建中间 map 或切片。

用 Take 截断，再收集结果

如果只需要前几个匹配项，可以把截断逻辑放在靠近消费端的位置：

func Take[K, V any](src iter.Seq2[K, V], limit int) iter.Seq2[K, V] {
	return func(yield func(K, V) bool) {
		if limit = limit {
				// 已经达到配额，通知上游停止。
				return false
			}
			count++
			// 下游提前停止时同样立即结束整条链。
			return yield(key, value)
		})
	}
}

func Collect[K comparable, V any](src iter.Seq2[K, V]) map[K]V {
	result := make(map[K]V)
	for key, value := range src {
		// 收集器消费完整链路；重复键按 map 赋值规则覆盖。
		result[key] = value
	}
	return result
}

组合调用示例：

source := FromMap(map[string]int{
	"go": 3, "iter": 2, "seq2": 1, "skip": 0,
})

selected := Take(
	Filter(source, func(key string, value int) bool {
		// 只保留正数，false 只跳过当前元素。
		return value > 0
	}),
	2,
)

result := Collect(Map(selected, func(key string, value int) (string, string) {
	// 映射阶段只改变输出形状，不改变停止协议。
	return key, fmt.Sprintf("value=%d", value)
}))

上面的链条不会承诺 map 的遍历顺序，但会承诺停止方向：Collect 请求结束时，Map、Take、Filter 会把结果逐层传回 FromMap。如果业务需要稳定的前两项，应该先定义排序或使用本身有顺序的来源，而不是依赖偶然输出。

常见误区与排查清单

可以用下面的清单检查一个自定义 Seq2 是否适合组合：

• 签名是否确实是 func(func(K, V) bool)，而不是把两个值塞进结构体后再传递？
• 每一次调用下游 yield 后，是否都检查并传播了 false？
• 适配器跳过当前元素时，是否仍返回 true 让上游继续？
• 文档是否写清遍历顺序、是否单次使用，以及底层集合的并发限制？

小结

iter.Seq2 的核心不是“把 map 变成另一种容器”，而是规定一条可传递的键值回调协议。生产者负责产生并尊重停止信号，过滤器负责决定是否转发，映射器负责改变形状，截断器负责把配额转成停止信号，收集器最后决定是否落地为 map 或其他结构。只要每层都保留这条协议，键值遍历就能按需组合，而不会被中间容器和隐含顺序绑死。

相关问题

iter.Seq2 和直接返回 map 有什么区别？

map 适合已经拥有完整结果并需要按键访问的场景；Seq2 适合延迟产生、过滤、映射或提前停止的遍历链。

yield 返回 false 后还能继续调用吗？

不应该。调用方已经宣布停止，生产者应立即返回，适配器也要把这个 false 向上游传递。

如何让 iter.Seq2 的结果稳定排序？

先把键收集到切片，显式排序后再按排序后的键生成 Seq2；不能把 map 的自然遍历顺序当作排序结果。