Go iter 怎样在 range 函数中提前停止遍历

Go 1.23 开始，iter.Seq 可以直接作为 range 的遍历对象。想提前停止时，消费端通常只需要在满足条件后写 break；这个停止信号会让编译器生成的 yield 返回 false，迭代器收到后应立即结束生产。

官方资料：https://pkg.go.dev/iter、https://go.dev/blog/range-functions、https://go.dev/doc/go1.23。

先把 iter.Seq 看成带 yield 的函数

iter 包为 Go 的函数迭代器定义了两个常用类型：Seq 传递一个值，Seq2 传递两个值。本文只讨论单值的 Seq。它不是保存数据的容器，而是一段接收回调并逐项交付数据的函数。

package main

import (
	"fmt"
	"iter"
)

func numbers(limit int) iter.Seq[int] {
	return func(yield func(int) bool) {
		// 每次把一个整数交给调用方，yield 的结果决定是否继续。
		for i := 0; i 

可以把它理解成一条单向链路：迭代器调用 yield 交付元素，range 循环体消费元素，循环体是否继续又会反馈给迭代器。这样，停止并不是迭代器凭空猜出来的，而是消费端通过回调结果明确传回去。

在 range 循环中用 break 停止消费

如果只想读取前几项，最直观的写法就是在 range 循环里使用 break。下面的例子让迭代器最多产生 100 个数，但消费端在读到 3 后停止，后面的值不会继续进入循环体。

package main

import (
	"fmt"
	"iter"
)

func countUpTo(limit int) iter.Seq[int] {
	return func(yield func(int) bool) {
		for i := 1; i 

这里的 break 只影响当前这层 range 循环。它不会把迭代器变成可重新定位的游标，也不会自动保存“下次从哪里继续”的状态。若迭代器本身是一次性序列，停止后再次使用还要遵守它自己的生命周期约定。

在迭代器内部响应 yield 的 false

自定义 Seq 时，最重要的代码不是循环本身，而是 if !yield(item) { return } 这个守卫。它把消费端的提前停止转换为生产端的立即退出，避免数据源继续读取或继续执行昂贵的计算。

package main

import (
	"fmt"
	"iter"
)

func positive(values []int) iter.Seq[int] {
	return func(yield func(int) bool) {
		for _, value := range values {
			if value 

如果把 yield 当成普通的“只负责传值的函数”，就容易漏掉返回值检查。短序列可能看不出问题，但在文件扫描、分页读取或计算型迭代中，忽略 false 会让生产端无意义地继续工作。

自然结束、break 和 panic 不是一回事

迭代器自然跑完时，生产函数从末尾返回；消费端执行 break 时，yield 会先把停止结果反馈给生产端，生产端再通过 return 收尾。这两条路径的共同点是：迭代器最终都应停止调用 yield。

iter 文档明确说明，yield 在返回 false 后再次被调用会触发 panic。这个约束让迭代器作者能及时发现“停止之后仍继续生产”的错误，也意味着收尾代码必须放在 false 分支上，而不是让循环无条件继续。

把提前停止接到前 N 项和命中条件

实际使用中，提前停止通常有两种表达：只消费前 N 项，或找到满足条件的元素后退出。两者都应把停止逻辑放在消费端，把资源和计算的停止响应放在 Seq 内部。

package main

import (
	"fmt"
	"iter"
)

func values(items []string) iter.Seq[string] {
	return func(yield func(string) bool) {
		for _, item := range items {
			// 数据源每次只交付一个字符串，避免一次复制整个切片。
			if !yield(item) {
				return
			}
		}
	}
}

func main() {
	seen := 0
	for item := range values([]string{"A", "B", "C", "D"}) {
		fmt.Println(item)
		seen++
		if seen == 2 {
			// 前两项已经足够，停止当前消费。
			break
		}
	}
}

这个结构适合分页预览、只取首个匹配项、限制日志扫描量等场景。如果数据源背后还持有文件、锁或网络连接，迭代器的实现者应把释放动作放在自己能保证执行的生命周期里；break 只负责停止当前遍历，不替代资源管理设计。

几个容易踩到的边界

• 版本边界：range 直接遍历函数形式是 Go 1.23 的能力，旧版本不能照抄同一语法。
• 返回值边界：每次调用 yield 都要检查布尔结果，false 分支要立即退出。
• 控制流边界：break 停止的是当前 range，不会自动让序列可恢复或可重放。
• 生命周期边界：一次性迭代器可能不能安全地被第二次消费，是否可复用要看具体实现的文档约定。
• 错误边界：如果数据源还会返回错误，不能用“遍历自然结束”冒充“没有错误”，应在迭代器或外部状态中明确表达错误。

常见问题

range over iter.Seq 时怎样只取第一项？

在循环体处理第一项后执行 break，并确保迭代器在 yield 返回 false 时立即 return。

为什么自定义 Seq 不能忽略 yield 的返回值？

因为消费端的 break 会通过这个返回值通知生产端停止。忽略它会继续生成后续数据，且在停止后再次调用 yield 可能触发 panic。

break 之后能不能从原位置继续 range？

不能把它当成通用的暂停功能。是否能继续取决于迭代器是否显式保存状态；普通函数返回的 Seq 不会因为 break 自动提供恢复游标。

这条规则可以浓缩成一句话：消费端用 break 表达“不再要了”，生产端检查 yield 的 false 并立即 return。只要两端都遵守这个约定，iter.Seq 的提前停止就会清晰、可控。