iter.Seq2 错误值被吞掉时的返回链修复

iter.Seq2[T, error] 的错误被吞掉，通常不是 Seq2 自身的问题，而是返回链中某一层把第二个值写成了 _、固定改成 nil，或者消费端遇错后只 break 却最终返回 nil。修复原则很简单：错误由数据源产生，经适配器用 yield(zero, err) 传给下游，消费者收到后立即返回；任一层都不能改写为“正常结束”。

需要先说明，标准库只把 iter.Seq2[K,V] 定义为“双值序列”，第二个值并不天然等于错误。把它实例化为 iter.Seq2[T,error] 是应用层约定。既然采用了这个约定，就要让所有适配器都保留这条错误通道。

错误为什么会在 Seq2 链路里消失

一条常见链路包含数据源、转换适配器和消费者。文件打开失败或扫描失败先进入源；适配器可能做裁剪、解析或过滤；消费者最终收集结果。如果任一层丢弃 error，下游看到的只是提前结束或一份不完整数据。

// TrimBad 会把上游错误直接丢弃，是典型的吞错写法。
func TrimBad(input iter.Seq2[string, error]) iter.Seq2[string, error] {
    return func(yield func(string, error) bool) {
        for value, _ := range input {
            // 错误被替换成 nil，下游无法区分失败与正常数据。
            if !yield(strings.TrimSpace(value), nil) {
                return
            }
        }
    }
}

这里有两个信号不能混为一谈：error 描述业务或 I/O 失败，yield 的布尔返回值描述消费者是否还要更多元素。错误不应该借助 yield(false)“暗示”给下游，因为下游只会把它理解为停止，不会得到错误对象。

最小修复配方

适配器遇到错误时，用目标值类型的零值占位，把错误交给 yield，随后立即返回。正常值才进入转换逻辑。这样错误只报告一次，也不会在失败后继续产出看似有效的数据。

// Trim 保留上游错误，并为当前适配器补充上下文。
func Trim(input iter.Seq2[string, error]) iter.Seq2[string, error] {
    return func(yield func(string, error) bool) {
        for value, err := range input {
            if err != nil {
                var zero string
                // 错误传给下游后立即结束当前序列。
                yield(zero, fmt.Errorf("trim input: %w", err))
                return
            }

            if !yield(strings.TrimSpace(value), nil) {
                // 消费者提前停止时，不再读取上游。
                return
            }
        }
    }
}

%w 保留原错误，使消费端仍可用 errors.Is 或 errors.As 判断根因。上下文应说明当前适配器做什么，例如 trim input、decode record，不要重复堆叠同一句“处理失败”。

修复转换适配器里的丢失点

转换函数最容易吞错，因为开发者只关注第一个值。排查时搜索三类写法：循环变量使用 _ 接收错误；调用 yield 时第二个参数固定为 nil；捕获错误后仅记录日志并继续。日志不是错误返回，除非接口明确允许跳过坏记录，否则继续产出会让调用方误以为结果完整。

如果业务真的需要“坏记录跳过、好记录继续”，不要把错误静默丢掉。可以显式返回结构体，把解析状态作为数据的一部分；或者增加错误回调、统计计数和最终汇总。这样调用方知道这是容错模式，而不是意外吞错。

消费端不要 break 后返回 nil

另一类问题发生在链路末端：循环里发现错误后执行 break，循环外却统一返回 nil。正确做法是当场返回错误，或者先保存错误并在循环结束后返回。

// CollectErr 把序列收集为切片，并保留第一处错误。
func CollectErr[T any](seq iter.Seq2[T, error]) ([]T, error) {
    values := make([]T, 0)

    for value, err := range seq {
        if err != nil {
            // 立即返回，避免把部分结果伪装成完整成功。
            return nil, err
        }
        values = append(values, value)
    }

    return values, nil
}

是否保留部分结果需要在 API 层明确约定。最保守的写法像上面一样返回 nil, err；如果调用方需要已成功的数据，可以返回 values, err，但文档必须说明切片只是错误发生前的前缀。

使用 Pull2 时别把 ok 当成错误状态

iter.Pull2 把推送式序列变为 next 和 stop。当原序列类型是 iter.Seq2[T,error] 时，next() 返回 (T, error, bool)：第三个 bool 只说明这一对值是否有效，第二个 error 才是业务错误。

// FirstErr 展示 Pull2 的三返回值判断顺序。
func FirstErr[T any](seq iter.Seq2[T, error]) (T, error) {
    next, stop := iter.Pull2(seq)
    defer stop() // 未读完整个序列时确保释放上游资源。

    value, err, ok := next()
    if !ok {
        var zero T
        return zero, io.EOF
    }
    if err != nil {
        var zero T
        return zero, err
    }
    return value, nil
}

不要写成 if !ok || err != nil { return zero, nil }，这会同时抹掉“序列为空”和“源失败”两种信息。官方文档还要求：当 next 尚未返回 false 而调用方不再读取时，应调用 stop；通常直接 defer stop()。

完整片段：从文件源到收集函数

下面把错误源、修复后的适配器和消费端连在一起。示例重点是返回链，不在本轮声称已经执行。

package main

import (
    "bufio"
    "fmt"
    "iter"
    "os"
    "strings"
)

// Lines 逐行产出文本，打开与扫描错误都走第二个返回值。
func Lines(path string) iter.Seq2[string, error] {
    return func(yield func(string, error) bool) {
        file, err := os.Open(path)
        if err != nil {
            var zero string
            yield(zero, fmt.Errorf("open %s: %w", path, err))
            return
        }
        defer file.Close()

        scanner := bufio.NewScanner(file)
        for scanner.Scan() {
            if !yield(scanner.Text(), nil) {
                // 消费者提前停止时立即返回并关闭文件。
                return
            }
        }

        if err := scanner.Err(); err != nil {
            var zero string
            // 扫描错误只报告一次，报告后结束序列。
            yield(zero, fmt.Errorf("scan %s: %w", path, err))
        }
    }
}

// NonEmpty 清理空白并过滤空行，同时保持错误返回链。
func NonEmpty(input iter.Seq2[string, error]) iter.Seq2[string, error] {
    return func(yield func(string, error) bool) {
        for line, err := range input {
            if err != nil {
                var zero string
                yield(zero, fmt.Errorf("read line: %w", err))
                return
            }

            line = strings.TrimSpace(line)
            if line == "" {
                continue
            }
            if !yield(line, nil) {
                return
            }
        }
    }
}

// LoadLines 返回完整结果；任一错误都会沿调用链返回。
func LoadLines(path string) ([]string, error) {
    return CollectErr(NonEmpty(Lines(path)))
}

快速排查清单

• 数据源是否在打开失败和读取失败时都调用了 yield(zero, err)？
• 每个适配器是否完整接收 value, err，而不是使用 _？
• 错误传给下游后是否立即 return，避免继续产出？
• 消费端是否直接返回错误，而不是 break 后返回 nil？
• 使用 Pull2 时是否区分了 err 与 ok，并确保调用 stop？

相关问题

为什么 Seq2 不直接规定第二个值是 error？ 因为它是通用的双值迭代器，也常用于键值对；错误语义由具体 API 的类型实例化和文档决定。

错误发生后还能继续 yield 正常值吗？ 技术上可以，但容易让消费者误解。默认建议第一处错误后结束；需要容错时应设计显式结果类型。

yield(error) 返回 false 还要处理吗？ 错误已经交给消费者，适配器无论得到 true 还是 false 都应结束，因此通常调用一次后直接 return。

官方资料在哪里？ 可参考 Go iter 包文档和 Go Blog：Range Over Function Types。