Go 迭代器如何提前停止：range over function 与错误传播的收尾方式

Go 1.23 之后，迭代器不必先把全部结果装进切片，也不必退回 channel 才能交给 for range。返回 iter.Seq[T] 的函数可以把值交给 yield，而调用方的 break 或 yield 返回 false 会让生产端及时收尾。真正容易写错的地方，是“停止遍历”和“业务失败”不是同一个信号：前者只表示不用更多值，后者还需要把错误带回调用方。

先把“停止”与“失败”分开

很多业务场景下我们需要按页拉取订单数据，只要读到第一条符合筛选规则的记录就直接终止流程。过去常见的实现方案要么直接返回全量切片，要么开goroutine往channel里塞数据。这两种写法虽然都能跑通，但前者很容易提前申请大量没必要的内存，后者又得额外处理channel关闭、阻塞、上下文取消等一堆边角逻辑。

iter.Seq[T] 的核心是一个函数：它接收 func(T) bool 类型的 yield。生产端每拿到一个值就调用一次 yield。调用方继续遍历时返回 true，调用方执行 break 后，运行时会让后续的 yield 返回 false。

用一个分页迭代器看清收尾路径

下面的示例把每页读取抽象成回调。为了让文章保持可运行，数据源用内存切片模拟；真实项目里可以把 loadPage 换成数据库查询或远程请求。

package main

import (
    "errors"
    "fmt"
    "iter"
)

var errPage = errors.New("page 2 unavailable")

func orders() (iter.Seq[string], func() error) {
    var saved error
    pages := [][]string{{"A-100", "A-101"}, {"A-102"}, {"A-103"}}

    return func(yield func(string) bool) {
        for pageNo, page := range pages {
            if pageNo == 1 {
                saved = errPage
                return
            }
            for _, order := range page {
                if !yield(order) {
                    return
                }
            }
        }
    }, func() error { return saved }
}

func main() {
    seq, errOf := orders()
    for order := range seq {
        fmt.Println(order)
        if order == "A-100" {
            break
        }
    }
    fmt.Println("err:", errOf())
}

这段代码打印出 A-100 后就结束，分页函数不会继续读取第二页。此时 errOf() 是 nil，因为调用方主动停止并不是数据源失败。

错误为什么要由迭代器额外保存

iter.Seq[T] 的函数签名只有一个 yield 参数，没有可以直接返回的 error。如果第二页读取失败，最小可靠做法是让迭代器和错误读取函数成对返回，或者返回一个带错误状态的方法对象。关键不在于选哪种封装，而在于错误必须有明确的所有权，并且只在生产端确认失败时写入。

如果调用方已经 break，生产端收到 false 后应直接返回，不要再把“用户不需要更多值”写成错误。反过来，数据库超时、响应解析失败等真实故障必须先保存，再结束迭代，让调用方在循环之后检查。

生产环境里要补上的边界检查

生产目标：避免无意义的后续读取

迭代器适合“找到一个就停”“只取前 N 条”“下游过滤后不再需要剩余页”的场景。生产端每次调用 yield 后都要判断返回值，不能无条件继续下一页。否则表面上调用方已经结束，网络或数据库读取仍可能继续。

安全配置：让错误状态只写一次

错误保存变量不要在多个 goroutine 中共享。一个普通的 range 遍历是串行调用的，最简单的闭包变量就足够；如果把迭代器再包装成异步管道，就必须重新设计取消与同步，不能直接把这个示例改成并发写入。

日志审计：记录停止原因而不是只记“结束”

线上排查问题的时候，至少要把三类执行状态明确区分开：遍历自然走完所有数据、调用方主动break跳出循环、数据生产侧发生了业务错误。你可以在分页读取的逻辑里埋点记录当前页码，用统一的变量记录业务错误，等调用方的遍历循环结束后再统一校验最终状态。这样线上出现“只读取了一页就终止”的情况时，你才能准确判断是提前命中了目标数据，还是中间某一步请求出错提前退出了。

发布前用测试验收两条路径

测试不要只覆盖完整遍历，还要覆盖调用方提前 break。第一条路径应确认所有页都被读取且错误为空；第二条路径应确认 yield=false 后没有继续加载下一页。再加一条错误路径，验证错误能在循环之后被读到。

for value := range seq {
    if want(value) {
        got = value
        break
    }
}
if err := errOf(); err != nil {
    return fmt.Errorf("iterate orders: %w", err)
}

这里的状态检查顺序一定要理清楚：先等遍历循环完整走完所有逻辑，再去读取保存的错误变量，别每拿到一个遍历值就提前猜流程是不是已经失败了。如果你的业务需要同时返回遍历过程中拿到的部分结果和最终错误，直接把这两个字段封装到一个明确的结果结构体里就行，完全没必要让调用方去猜闭包变量的赋值时机和生命周期。

常见问题

调用方执行 break 后，迭代器一定会立刻停止吗？

对标准的 range over function 迭代而言，后续的 yield 会得到 false，生产函数应据此返回。若生产端忽略返回值，仍可能继续做自己的工作，所以停止责任也在迭代器实现者。

能不能直接让迭代器返回 error？

不能把普通的 iter.Seq[T] 签名改成带 error 的返回形式后继续直接用于 for range。可以用闭包保存错误、返回结果对象，或者在业务层定义带状态的方法，但要保持错误检查路径可见。

什么时候 channel 仍然更合适？

需要真正的生产者与消费者并发、跨 goroutine 背压或多路合并时，channel 仍有价值。只是在单 goroutine 的惰性遍历和可提前停止场景里，iter.Seq 的收尾路径更短。

最后的检查清单

• 生产函数是否检查了每次 yield 的 bool 结果。
• 主动停止是否没有被记录成业务错误。
• 真实读取错误是否能在遍历结束后被调用方检查。
• 测试是否覆盖自然结束、提前停止和错误返回三条路径。