Go 泛型迭代器怎么安全消费：iter.Seq、提前停止与资源释放边界

线上导入任务把一批记录交给下游处理时，通常只需要找到第一个匹配项就可以停下。如果这批记录背后连着文件、游标或分页请求，for range 里的 break 只是停止消费，不会替你猜出所有清理动作。Go 1.23 的 iter.Seq 把“值怎么送出来”和“什么时候可以停”放进了同一个约定里，关键是让迭代器在收到停止信号后立刻收尾。

把 false 当成迭代器的停止协议：push 迭代器要在 yield 返回 false 时退出；通过 iter.Pull 消费时，只要没有读到结尾，就必须调用返回的 stop 函数。

先把两种迭代方式分开

iter.Seq[T] 是一个接收 yield func(T) bool 的函数。迭代器负责调用 yield，yield 返回 false 就表示调用方不再需要后续值。这个模式适合直接写 for value := range seq，循环中的 break 会让 yield 返回 false，迭代器因此得到退出机会。

而 iter.Pull 把同一个序列转换成 next 和 stop 两个函数：前者一次取一个值，后者负责在未读完时结束内部协作。它适合并排比较两个序列、把下一项交给状态机，或者消费方需要明确掌握读取节奏的场景。

push 迭代器要把停止信号传到底

下面这个例子模拟从分页游标中逐条读取数据。示例中的 openCursor、nextRecord 和 close 代表真实项目里的文件句柄或数据库游标；重点不是接口名称，而是关闭动作和 yield 调用处于同一个生命周期。

type Record struct {
    ID    int
    State string
}

func Records(c *Cursor) iter.Seq[Record] {
    return func(yield func(Record) bool) {
        defer c.Close()
        for {
            record, ok := c.Next()
            if !ok {
                return
            }
            if !yield(record) {
                return
            }
        }
    }
}

func FirstPending(c *Cursor) (Record, bool) {
    for record := range Records(c) {
        if record.State == "pending" {
            return record, true
        }
    }
    return Record{}, false
}

defer c.Close() 放在迭代器函数内部，意味着正常读完和提前停止都走同一条收尾路径。真正容易出错的是把游标创建放在调用方，却把关闭动作遗漏在迭代器外面；那样调用方一旦 break 或提前 return，资源责任就会变得模糊。

安全边界在 yield 返回 false 的瞬间

迭代器不要无条件继续调用 yield。下面这种写法虽然看上去也能遍历，但调用方停止后，迭代器仍会继续取数据，分页读取、日志写入或指标统计都可能多走一段。

// 不建议：忽略 yield 的返回值
for c.Next() {
    yield(c.Record())
}

// 建议：停止信号沿当前调用栈返回
if !yield(record) {
    return
}

这里的“停止”不是并发取消。它只表示当前序列不再需要后续值，迭代器应同步返回并完成自己的清理。如果底层读取本身是阻塞的，还要另外设计 context 或关闭底层句柄的机制，不能把 yield 的 false 当成网络超时方案。

Pull 消费时别漏掉 stop

Pull 迭代器最容易留下隐患：消费方只取前几项就返回，却没有告诉内部协作方结束。官方约定要求在没有读到末尾时调用 stop，因此把它写成紧邻 Pull 的 defer 最稳妥。

func SamePrefix[T comparable](left, right iter.Seq[T], n int) bool {
    nextLeft, stopLeft := iter.Pull(left)
    defer stopLeft()
    nextRight, stopRight := iter.Pull(right)
    defer stopRight()

    for i := 0; i 

两个 stop 都要独立登记，不能因为左边已经结束就省略右边。若循环自然读到 false，stop 仍然可以安全调用；把清理动作写成 defer，能覆盖比较失败、提前 return 和未来新增错误分支。

用三类检查验证迭代器契约

我会把检查拆成“值是否正确、停止是否及时、资源是否关闭”三层。只断言最终返回值，容易漏掉第二层和第三层。

检查完整遍历

让序列走到末尾，确认每个值都出现一次，且游标关闭标记为 true。这个用例能发现漏读和正常路径未关闭的问题。

检查提前 break

只消费第一个满足条件的记录，断言底层读取次数没有继续增长，关闭标记也已经完成。这个用例对应线上“找到目标就返回”的真实路径。

检查 Pull 的早退

只调用一次 next 后直接返回，确认 defer 注册的 stop 被执行。不要只测完整读完，因为完整读完会掩盖忘记 stop 的代码。

几个容易混淆的边界

第一，slices.Collect 会把迭代器全部收集到新切片，适合结果规模明确的场景；它不是流式消费，也不会替你降低结果内存。第二，map 的遍历顺序没有稳定保证，基于 maps.All 的测试不要把顺序当作契约。第三，迭代器只定义值的传递协议，业务层的取消、超时和重试仍要通过明确的 context、错误值或上层状态机表达。

常见问题

for range 里的 break 会自动关闭文件吗？

只有迭代器函数自己把关闭动作放在 defer 或等价的收尾逻辑里，break 才能沿停止路径触发它。语言不会替一个独立创建的文件句柄自动补 Close。

iter.Pull 读到末尾后还要调用 stop 吗？

可以调用，而且把 stop 放进 defer 更不容易漏掉。它的主要价值是覆盖尚未读到末尾就提前返回的路径。

迭代器一定比普通 for 循环快吗？

不一定。迭代器更像统一的组合协议，是否更快要用目标数据量、分配次数和实际基准测试判断；简单切片遍历通常没必要为了形式改写。

把停止协议写进代码评审清单

审查一个 iter.Seq 时，先找每次 yield 的返回值是否被处理，再看资源创建和关闭是否位于同一生命周期。审查 iter.Pull 时，确认每个 next 都有配对的 stop，并覆盖提前返回测试。这样迭代器才不仅“能跑”，还把停止、错误和资源边界交代完整。