迭代器里的错误应该通过什么方式返回

Go 的 iter.Seq 本身不返回 error。它通过 yield 的 bool 表示“继续还是停止”，所以这个布尔值不能拿来传递数据库、文件或网络错误。更稳妥的做法是：创建迭代器前就能发现的错误，作为外层 error 返回；遍历途中发生的错误，放进每个元素携带的结果对象里。

先把两类错误分开：创建失败和遍历失败

如果打开文件、建立数据库连接或解析查询条件在返回迭代器之前就失败，接口可以直接写成 (iter.Seq[T], error)。调用方先处理这个错误，拿到非空迭代器后再进入 range。这种写法最接近普通 Go 函数，也不会让消费者为了找一个初始化错误而先遍历一次。

真正棘手的是遍历已经开始后才出现的错误。例如流式解码读到半截数据，或者下一页请求返回失败。标准 iter.Seq 的函数类型没有错误出口，不能偷偷把错误写进 yield=false；后者只代表消费者主动停止，迭代器应据此释放自己的资源并返回。

用结果对象让每一项携带值或错误

对逐条读取的场景，可以定义一个小型结果类型。成功项填充 Value，失败项填充 Err；错误发生后通常只发出一个错误结果，然后结束迭代。这样既保留了 for range 的自然写法，也不会丢失“已经成功读到的部分结果”。

package records

import (
    "fmt"
    "iter"
)

// Result 表示一次读取的结果：成功时有 Value，失败时有 Err。
type Result[T any] struct {
    Value T
    Err   error
}

// ReadAll 演示遍历途中如何把错误放入序列元素。
func ReadAll[T any](src []T, failAt int) iter.Seq[Result[T]] {
    return func(yield func(Result[T]) bool) {
        for i, value := range src {
            if i == failAt {
                // 错误作为最后一个结果传出，然后结束值流。
                _ = yield(Result[T]{Err: fmt.Errorf("读取第 %d 项失败", i)})
                return
            }
            // 消费端返回 false 时，表示它主动停止，不是业务错误。
            if !yield(Result[T]{Value: value}) {
                return
            }
        }
    }
}

func Consume[T any](seq iter.Seq[Result[T]]) ([]T, error) {
    var values []T
    for result := range seq {
        if result.Err != nil {
            // 这里决定停止并把原始错误交给上层。
            return values, result.Err
        }
        values = append(values, result.Value)
    }
    return values, nil
}

示例里的 failAt 只是说明错误边界，真实实现可以把文件解码错误、响应体错误或游标读取错误映射到同一个结果类型。若业务允许“错误后继续”，则不要立刻返回，而是记录错误并继续发出后续结果；这时最好把状态定义清楚，避免调用方把缺省值误认为成功值。

消费端检查错误，再决定是否提前停止

消费端的判断顺序很重要：先看 Err，再使用 Value；遇到错误后用 break 或直接从当前函数返回。迭代器内部看到 yield 返回 false 时，只需要停止生产和清理资源，不应该再构造一个“消费者停止错误”。

iter.Seq2[K,V] 虽然能传两个值，但第二个值的语义通常是键值对中的值。把它硬改成“数据加 error”会让公共 API 不直观；除非你的序列天然就是二元记录，否则 Result[T] 更容易读懂，也更方便以后增加阶段、偏移量或重试信息。

pull 迭代器仍然需要 stop 处理资源

需要并行消费两个序列，或必须逐次请求下一个元素时，可以用 iter.Pull 把 push 迭代器转换为 pull 形式。next 返回值和是否还有数据，错误仍应放在值本身；如果没有读到序列末尾就退出，必须调用 stop，让底层的 yield 收到停止信号。

package records

import "iter"

// PullFirst 只读取第一个错误或目标记录，返回后由 defer 确保 stop 执行。
func PullFirst[T any](seq iter.Seq[Result[T]]) (T, error, bool) {
    next, stop := iter.Pull(seq)
    defer stop() // 提前返回时也要通知生产端结束。

    result, ok := next()
    if !ok {
        var zero T
        return zero, nil, false
    }
    if result.Err != nil {
        var zero T
        return zero, result.Err, true
    }
    return result.Value, nil, true
}

这里的第三个返回值表示“是否拿到过一项”，不是错误标记：空序列、成功值和错误结果是三种不同状态。若需要拉取到结束，仍建议保留 defer stop()，这样实现细节变化后也不会遗漏清理。

按错误时机选择公开接口

常见问题

yield 返回 false 能不能当成错误返回？

不能。它表达的是消费端不再需要后续值，迭代器应停止并清理资源；业务错误要放进结果对象或由外层接口返回。

结果对象里同时有 Value 和 Err 可以吗？

可以，但公共约定要明确。更推荐成功时只填 Value，失败时只填 Err，避免调用方不知道该相信哪个字段。

错误结果发出后还要继续迭代吗？

默认在第一个不可恢复错误后结束。只有业务明确允许跳过坏记录时才继续，并应额外提供错误收集或状态字段。