怎样把推送式回调适配成 Go 迭代器

把推送式回调适配成 Go 迭代器，核心不是再包一层函数，而是让回调遵守 iter.Seq[T] 的停止协议：每产出一个值就调用一次 yield，收到 false 立即返回。这样调用方可以直接使用 for v := range seq，而文件、游标或分页流的清理责任仍由适配器持有。

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

先把 push callback 对齐到 Seq 协议

旧接口常见写法是 Walk(func(Item) bool)：数据源主动把 Item 推给调用方，调用方返回 false 表示不再需要。这个形状已经非常接近 iter.Seq[Item]，适配器只需把数据源调用放进闭包，并把 yield 原样传进去。不要在中间偷偷收集成 slice，否则会失去流式消费和提前停止的优势。

package records

import "iter"

type Item struct {
	ID   int
	Name string
}

// LegacyWalk 保留旧回调协议：返回 false 就停止继续推送。
func LegacyWalk(emit func(Item) bool) {
	for _, item := range []Item{{1, "alpha"}, {2, "beta"}, {3, "gamma"}} {
		if !emit(item) {
			return // 尊重消费者的提前停止，避免多做一次工作。
		}
	}
}

// Items 把旧 push callback 适配为标准 iter.Seq，调用方可直接 range。
func Items() iter.Seq[Item] {
	return func(yield func(Item) bool) {
		LegacyWalk(yield)
	}
}

这里的关键是“false 的方向一致”：range 提前结束会让 yield 返回 false，LegacyWalk 收到它后返回，整个调用栈自然收敛。适配器不应把 false 改成继续，也不要在回调返回后再次调用 yield。

把错误、分页和清理放在适配器边界

iter.Seq 只承载值和停止信号，不额外承载 error。若旧数据源有错误，实务上可以让适配器在停止前保存错误，再提供一个伴随方法读取；或者把错误作为 Seq2[Item, error] 的值域。不要为了“看起来像迭代器”而吞掉错误。

如果资源在创建 Seq 时就打开，调用方甚至没有开始 range 也可能占用资源。更稳妥的边界是把打开、读取、关闭放进 Seq 函数体，并让 defer cleanup() 覆盖正常结束、消费者 break 和数据源错误三条路径。

需要逐项拉取时用 Pull，并明确 stop 责任

大多数业务直接 range 就够了；只有旧代码必须调用 next()，或者需要把两个迭代器交错读取时，才把 push 形式转换成 pull 形式。iter.Pull 返回 next 与 stop，未读完就离开时必须停止。

package records

import (
	"fmt"
	"iter"
)

// FirstTwo 演示只取前两个值时，如何保证 Pull 背后的 Seq 能收到 stop。
func FirstTwo(seq iter.Seq[Item]) {
	next, stop := iter.Pull(seq)
	defer stop() // 提前返回或 break 时释放迭代器内部资源。

	for i := 0; i 

并发边界也要说清：同一个 next 或 stop 不能被多个 goroutine 同时调用。对于网络流、文件扫描这类不可回放来源，还应在文档中注明它是单次迭代器；Seq 这个类型本身并不保证每次调用都会从头开始。

适配完成后的检查清单

• 回调收到 false 后，数据源是否立即 return？
• 资源是否在 Seq 内部创建，并由 defer 覆盖提前停止路径？
• 错误是显式返回、伴随值传递，还是被记录后可查询？
• 调用方是否真的需要 Pull；如果只需顺序消费，优先保留 range？
• 文档是否写明迭代器能否重复调用，以及 next/stop 的并发限制？

相关问题

推送回调能直接当作 iter.Seq 吗？

只有参数形状和停止语义都一致时才可以。若旧回调返回 error、接受 context 或使用其他停止约定，应先在适配器中明确转换。

为什么不先把回调结果收集到 slice？

收集会增加内存和首个结果的等待时间，也无法在消费者提前停止时避免后续读取；流式来源尤其不适合这样改。

range 提前 break 后还需要手动 stop 吗？

直接 range 消费标准 Seq 时由迭代协议完成返回；使用 iter.Pull 时则要显式 defer stop()，这是两种消费方式的责任差异。