Go iter.Pull 怎么安全消费迭代器：停止时机、资源释放与 goroutine 泄漏排查

线上把一个 push 迭代器接到分页、过滤或命令行处理流程时，iter.Pull 能让调用方用 next() 一项项取数据，但它不会替你决定什么时候结束。真正容易出问题的是：提前返回没有调用 stop()，生产者仍在等待，最后留下看不见的 goroutine。

先看清 iter.Pull 把谁放进了后台

传统 push 迭代器由回调驱动：生产者调用 yield，调用方在回调里处理值。iter.Pull 把这个关系翻过来，返回 next 和 stop 两个函数。每次调用 next，后台迭代器才继续向前走；因此调用方拥有读取节奏，也承担结束责任。

先用一个最小例子确认契约。这里的 stop 不是“把已经取到的值清空”，而是通知迭代器：调用方不再需要后续值了。

package main

import (
    "fmt"
    "iter"
)

func numbers() iter.Seq[int] {
    return func(yield func(int) bool) {
        for n := 1; n 

触发信号：提前返回后 goroutine 数量不回落

最常见的触发信号不是业务报错，而是测试偶发超时、进程的 goroutine 数量缓慢上升，或者某个迭代器生产任务一直卡在下一次 yield。尤其是只取前两项就返回的筛选逻辑，最容易把这个问题藏起来。

func firstMatch(seq iter.Seq[string], want string) (string, bool) {
    next, stop := iter.Pull(seq)
    defer stop()

    for {
        value, ok := next()
        if !ok {
            return "", false
        }
        if value == want {
            return value, true
        }
    }
}

这里的关键不是把 defer stop() 写得漂亮，而是保证所有退出路径都经过它：命中、没有命中、解析失败、上层取消都一样。不要只在循环自然走完的分支里调用。

快速判断：next 的两个返回值分别说明什么

next 返回的布尔值是迭代状态，不是业务数据里的真假字段。true 表示当前值有效；false 表示序列已经结束，此时返回的值不应继续处理。

消费端若要在中途停止，应该先退出自己的业务循环，再让 defer stop() 释放迭代器。不要为了“排空”而继续调用 next，除非你的业务明确需要拿完所有值。

处理步骤：把取消信号传到生产端

如果迭代器内部还要读文件、查库或等待网络，单独调用 stop 只能结束 Pull 关系；生产端自己的阻塞操作仍需要可取消。把 context.Context 放到生产函数里，让每一步等待都能退出。

func records(ctx context.Context) iter.Seq[Record] {
    return func(yield func(Record) bool) {
        for {
            record, ok := readOne(ctx)
            if !ok || ctx.Err() != nil {
                return
            }
            if !yield(record) {
                return
            }
        }
    }
}

func consume(ctx context.Context, seq iter.Seq[Record]) error {
    next, stop := iter.Pull(seq)
    defer stop()

    for {
        record, ok := next()
        if !ok {
            return nil
        }
        if err := validate(record); err != nil {
            return err
        }
        if ctx.Err() != nil {
            return ctx.Err()
        }
    }
}

排查时先确认 readOne 是否真的读取了取消信号，再看消费端是否覆盖所有返回路径。只给最外层函数加超时，而底层读取没有退出条件，通常只是把泄漏变成了延迟暴露。

回滚路径：不确定迭代器契约时先退回显式状态机

如果旧迭代器没有可靠的停止语义，先不要把它包成 iter.Seq 再接入关键链路。可以暂时保留显式的 channel、关闭函数和错误返回，把生产任务的退出条件写在同一个状态机里。等生产端能响应取消、测试能证明 goroutine 回落后，再切换到 Pull 形式。

这不是否定 iter.Pull，而是把迁移边界放在可验证的位置：能否停止、谁负责停止、停止后资源是否释放，三件事都要有答案。

告警确认：用测试和运行指标证明没有泄漏

测试至少覆盖三条路径：自然读完、命中条件后提前返回、生产端遇到取消。测试结束前记录 goroutine 数量，给后台任务一个有限等待窗口；如果数量持续增加或等待超时，就不要把失败归因给测试环境。

func TestFirstMatchStopsProducer(t *testing.T) {
    before := runtime.NumGoroutine()
    _, ok := firstMatch(records(context.Background()), "wanted")
    if !ok {
        t.Fatal("record not found")
    }

    deadline := time.Now().Add(500 * time.Millisecond)
    for runtime.NumGoroutine() > before+2 && time.Now().Before(deadline) {
        runtime.Gosched()
    }
    if runtime.NumGoroutine() > before+2 {
        t.Fatal("producer goroutine did not stop")
    }
}

线上则关注任务队列堆积、迭代批处理耗时和 goroutine 曲线的组合变化。单看 goroutine 总量容易误报，和同一批处理的成功数、取消数、超时数一起看，定位会快很多。

复盘清单：把 stop 责任写进代码评审

• 创建 next, stop 后，是否在同一函数立即安排了 defer stop()？
• 生产端的文件、数据库或网络等待，是否能响应 context 取消？
• 提前返回、校验失败和上游取消是否都通过了测试？
• 是否有 goroutine、耗时和取消数的结果证据，而不是只看“测试通过”？

相关问题

iter.Pull 什么时候不适合用？

当生产端没有可停止语义，或者调用方本来就需要批量并发处理时，显式的批处理接口往往更容易维护。先补齐退出契约，再考虑改成 Pull。

只写 defer stop 会不会太晚？

对普通函数返回路径来说，defer 是可靠的托底；但生产端的阻塞 I/O 仍应有自己的取消机制。两者是互补关系，不能互相替代。

总结

iter.Pull 的便利在于把 push 迭代器变成了按需读取，风险也正来自这个“按需”：调用方一旦不再调用 next，就必须明确调用 stop。用 defer stop() 覆盖返回路径，再让生产端观察 context，最后用取消测试和运行指标验收，才能把迭代器接入生产链路。