Go iter.Pull2 怎样消费键值迭代器并及时停止

如果一个 Go API 返回的是 iter.Seq2[K, V]，但当前代码更适合“一次拿一项”，可以用 iter.Pull2 把推送式迭代器转换成 next 和 stop。next 每次返回键、值和是否有效的布尔值；读到末尾或主动停止后，它会返回键和值的零值以及 false。

官方地址：https://pkg.go.dev/iter#Pull2

最重要的使用习惯只有一句话：只要没有确定读到结尾，就在拿到 stop 后立即用 defer stop()。这样即使循环中途返回、达到数量上限或遇到业务分支，也不会把迭代器停在半路。

iter.Pull2 返回的到底是什么

iter.Seq2[K, V] 是接收 yield func(K, V) bool 的函数，迭代器主动把一对值交给回调；而 Pull2 将它转换成拉取接口：

• next() (K, V, bool)：拉取下一对键和值，第三个返回值表示这一对是否有效。
• stop()：结束尚未读完的迭代器，让产生数据的一方完成收尾。

因此，false 不是某个键或值的业务状态，而是“没有可用的下一项”。这也是为什么代码必须先判断 ok，再使用键和值。读到末尾时，next 返回的是 K 和 V 的零值；如果业务上允许零值键或零值，就更不能省略这个判断。

用 next 消费键值并在合适位置 stop

下面用 maps.All 产生一个键值迭代器，再让 Pull2 提供传统循环可以理解的读取方式。示例只表达 API 关系，不把输出当作运行截图。

package main

import (
    "fmt"
    "iter"
    "maps"
)

func printFirstTwo(values map[string]int) {
    next, stop := iter.Pull2(maps.All(values))
    defer stop() // 中文注释：提前返回或达到数量上限时也要结束迭代器

    count := 0
    for {
        key, value, ok := next()
        if !ok {
            break // 中文注释：false 表示没有下一对键值，不能继续使用零值
        }
        fmt.Println(key, value)
        count++
        if count == 2 {
            return // 中文注释：示例只取两项，defer stop 负责善后
        }
    }
}

这里的关键不是把 map 变成有序列表，而是把一次调用的控制权交给调用方。映射的遍历顺序仍由迭代器提供方决定；如果业务需要稳定顺序，应先采用明确的排序或有序数据源，再交给 Pull2。

提前退出时为什么必须保留 stop

完整读到 next 返回 false 时，迭代器已经知道序列结束；但限量读取、筛选命中、错误返回等场景通常会在中途离开循环。此时如果不调用 stop，产生序列的函数可能还没有机会返回，相关资源也可能无法及时完成收尾。

stop 可以在已经读完或已经停止后再次调用，所以把它放进 defer 是稳妥的统一写法。代码不需要在每个 break、return 和错误分支旁边重复写清理动作。

func findValue(values iter.Seq2[string, int], wanted int) (string, bool) {
    next, stop := iter.Pull2(values)
    defer stop() // 中文注释：无论命中、读完还是提前返回，都结束拉取

    for {
        key, value, ok := next()
        if !ok {
            return "", false // 中文注释：序列耗尽，零值键不代表真实数据
        }
        if value == wanted {
            return key, true // 中文注释：命中后提前退出，由 defer stop 收尾
        }
    }
}

还要注意调用模型：同一组 next 和 stop 不能被多个 goroutine 同时调用。如果需要并发处理，应先在单一消费者中拉取，再把已经取出的数据交给其他 goroutine；不要让多个 goroutine 共享这两个函数。

什么时候直接 range，什么时候改用 Pull2

如果只是完整遍历，直接使用 for k, v := range seq 更短，也更符合迭代器的默认消费方式。只有当调用方需要把“下一项”封装成接口、一次只读取一项、在传统状态机里逐项推进，或者经常在中途退出时，Pull2 才更合适。

常见问题

next 返回 false 后还需要 stop 吗？

规范上读到结尾后再调用是安全的，重复调用也安全。工程上仍建议保留 defer stop()，因为同一个函数以后可能增加提前返回分支。

可以把 false 时返回的键和值继续使用吗？

不可以。此时它们只是类型零值，不代表有效的键值对；必须先判断布尔值。

Pull2 会把数据全部缓存起来吗？

它提供逐项拉取的消费接口，不应把它理解成自动收集切片。是否缓存、是否阻塞以及提前停止后的收尾行为，取决于提供 Seq2 的迭代器实现。

记住三点即可：next 的布尔值优先于键和值，未读完时始终保留 defer stop()，同一组拉取函数只由一个 goroutine 使用。这样 iter.Pull2 就能在键值流、限量读取和传统循环接口之间提供清晰的连接。