Go iter.Pull 怎样组合到一个小型工具中

我第一次把 iter.Pull 放进一个小工具，是因为一个已有的迭代器消费逻辑开始出现两个互相拉扯的需求：大多数时候希望顺着序列读取，遇到满足条件的值又要立即停下来；调用方还希望拿到一个普通的切片，而不是理解 yield 回调。

Go 1.23 引入的 iter 包正好提供了这层适配。iter.Pull 接收 push-style 的 iter.Seq，返回逐项取值的 next 和结束消费的 stop。把这两个函数包进一个小而明确的泛型工具，就能让业务代码只关心“哪些值要留下”，不必到处重复处理停止逻辑。

从 push 到 pull：先把接口边界拆开

iter.Seq[V] 的形态是 func(yield func(V) bool)：序列生产者拿到回调后，把每个值交给它；回调返回 false 时，生产者应当停止继续提供值。这种写法适合 for range，但不适合所有消费场景。例如，小工具想在每次消费后做一次判断，或者需要同时控制“取下一个值”和“结束当前序列”，就更适合 pull-style 接口。

iter.Pull(seq) 不会把整个序列一次性收集起来，而是返回一对函数。next() 每次返回一个值和一个布尔值；布尔值为 false 表示序列已经结束。stop() 用于调用方提前放弃剩余值时结束迭代。两者由同一个消费方串行调用，不能被多个 goroutine 同时调用。

先写一个最小的 Pull 消费层

先不要急着抽象工具。把 next 和 stop 的生命周期写清楚，后面的封装就容易判断边界了。下面的函数只负责从序列中读取第一个满足条件的值；如果序列提前结束，返回零值和 false。

package main

import "iter"

// FirstMatch 从序列中取出第一个满足条件的元素。
// 条件命中或序列自然结束后，defer 都会保证 stop 被调用。
func FirstMatch[V any](seq iter.Seq[V], match func(V) bool) (V, bool) {
	var zero V
	next, stop := iter.Pull(seq)
	defer stop() // 提前返回时也要结束未消费完的序列。

	for {
		value, ok := next()
		if !ok {
			return zero, false // 没有更多元素时返回零值和未命中标记。
		}
		if match(value) {
			return value, true // 命中后不再拉取后续元素。
		}
	}
}

这里最值得保留的是 defer stop()，而不是循环本身。自然读到末尾时，stop 仍然可以安全调用；提前命中时，它负责把尚未消费完的部分结束掉。官方文档也明确建议在不再关心后续值时调用 stop，并说明重复调用是允许的。

把 next 和 stop 封装进一个可组合的小工具

如果调用方不是只要一个值，而是想“收集一段满足条件的结果，然后停止”，可以在同一层加入一个结果切片。这个工具仍然只做三件事：从来源取得下一个值、根据条件决定是否保留、在停止条件满足时结束消费。

package iterkit

import "iter"

// TakeUntil 收集满足 keep 条件的值，直到 stopWhen 命中或序列结束。
// 它不修改来源序列，也不在内部启动 goroutine。
func TakeUntil[V any](seq iter.Seq[V], keep func(V) bool, stopWhen func(V) bool) []V {
	next, stop := iter.Pull(seq)
	defer stop() // stopWhen 提前命中时释放剩余迭代状态。

	result := make([]V, 0)
	for {
		value, ok := next()
		if !ok {
			return result // 序列自然结束，返回已经收集的结果。
		}
		if keep(value) {
			result = append(result, value) // 只把符合保留条件的值放入结果。
		}
		if stopWhen(value) {
			return result // 命中边界后不再请求下一个值。
		}
	}
}

例如，日志序列按时间产生，工具只想保留级别为 warning 或 error 的记录，并在遇到某个分区标记后停止。调用方只传入两个判断函数，来源仍然可以来自 slices.Values、maps.Keys 或自定义 iter.Seq。

三个边界决定这个工具是否可靠

尤其要注意“零值”和“结束”是两件事。iter.Pull 用第二个返回值表达有效性，所以 int(0)、空字符串或一个零值结构体都可以是正常元素。若把 value == zero 当作结束判断，小工具会在合法数据处提前退出。

什么时候用 Pull，什么时候继续用 range

这次封装让我更愿意把 iter.Pull 当成适配器，而不是默认迭代方式。只需要顺序遍历、没有提前停止资源语义时，for value := range seq 更直观；只想把序列变成切片时，标准库的 slices.Collect 更省代码。只有当消费方要在每次拉取之间插入控制逻辑、组合多个来源，或需要明确地在中途停止时，Pull 形式才更有价值。

我在小工具里保留的判断标准是：如果 next 和 stop 能让调用方看懂一个真实的边界，它们就值得被封装；如果只是把一个普通 range 循环改写成函数调用，抽象反而会增加阅读成本。

常见问题

iter.Pull 适用于哪个 Go 版本？

它属于 Go 1.23 引入的 iter 标准库包。项目的 go.mod 需要允许使用对应的标准库 API，旧版本项目应先评估工具链升级或保留原有迭代写法。

已经读到末尾，还需要调用 stop 吗？

可以调用。官方说明允许在 next 返回 false 后调用 stop，因此把它放在 defer 中通常最简单。

能不能让一个 goroutine 调用 next，另一个调用 stop？

不建议这样做。next 和 stop 不能被多个 goroutine 同时调用；如果确实需要并发消费，应先在外部设计明确的串行协调或消息传递边界。

参考资料：iter 包文档、Go 1.23 发布说明、Range Over Function Types。