迭代器、slices/maps 与数据流水线

Go 1.23 起标准库提供 iter，并允许 range 遍历函数形式的迭代器。它适合表达按需产生的数据，但并不意味着所有切片处理都应改成惰性流水线。要理解停止协议、一次或多次遍历、错误通道和资源生命周期。

一、学习目标

理解 Seq 与 Seq2 的 yield 协议
编写能尊重提前停止的迭代器
组合过滤、映射和收集操作
使用 slices 与 maps 的迭代器接口
判断何时惰性查询优于直接循环或切片

二、Seq 与 range-over-func

iter.Seq[V] 本质上是接收 yield 回调的函数：

func Pending(tasks []Task) iter.Seq[Task] {
    return func(yield func(Task) bool) {
        for _, task := range tasks {
            if task.Status() == StatusTodo && !yield(task) {
                return
            }
        }
    }
}

for task := range Pending(tasks) {
    fmt.Println(task.Title())
}

当 yield 返回 false，生产者必须立即停止。忽略返回值会继续做无用工作，若生产者持有文件或网络资源，还可能延迟释放。

三、组合与物化

迭代器可以组合映射与过滤，但 Go 标准库刻意保持小而基础。业务中可写少量明确辅助函数：

func Collect[T any](seq iter.Seq[T]) []T {
    var out []T
    for value := range seq {
        out = append(out, value)
    }
    return out
}

物化切片确定了一个时间点的快照，并允许重复遍历；惰性序列可能每次重新读取源或观察到变化。API 必须说明序列是可重复、一次性还是消费外部流。

四、标准 slices 与 maps

slices.Values、slices.All、maps.Keys 等返回迭代器，可与排序收集函数配合：

ids := slices.Sorted(maps.Keys(byID))
for _, id := range ids {
    fmt.Println(id)
}

map 键仍然无序，maps.Keys 不改变这一事实；需要稳定结果必须排序。slices.Collect 可物化序列。选择直接标准函数时，代码通常比自建通用流式框架更易读。

五、错误与取消

Seq 没有内建错误返回槽。可让元素包含结果结构、使用 Seq2[T,error] 约定，或让迭代器对象在结束后暴露错误，但每种方式都要明确消费规则。

对可能阻塞的源，应接受 context.Context 并在读取间隙检查取消。不能只在创建迭代器时检查一次。消费者提前 break 时，yield 返回 false 是停止信号；生产者若另起 goroutine，还必须保证该 goroutine收到停止通知。

六、选择直接循环

切片已经在内存中、逻辑只有一两步时，普通 for 循环最清楚，也容易处理错误和预分配。迭代器适合隐藏集合实现、按需生成大量数据或组合多步但无需全部物化的场景。

性能不能从“惰性”二字推断。闭包、间接调用、分支和无法预分配都可能增加成本。用基准比较直接循环、标准 slices 函数和迭代器版本，并同时看分配与可读性。

七、从知识点到工程契约

本篇的示例最终要进入可维护的 Go 包，而不是停留在 main 中的一次性片段。先把目标写成调用者可以观察的契约：输入是否允许零值或 nil，返回值是否是快照，错误能否通过 errors.Is/As 分类，函数是否启动 goroutine、取得资源或修改共享状态。然后再选择结构体、接口、函数值或泛型；抽象形式必须服务于契约，而不是反过来决定需求。

可以用以下顺序把知识点落到工程代码：

在独立小函数中写出最小成功路径，并让 go test 能直接调用。
加入一个与“忽略 yield 返回 false，消费者退出后仍继续生产”相关的失败样例，确认失败可观察且不会留下半完成状态。
把文件、网络、时间、环境或并发等外部因素改成显式依赖，测试使用临时目录、固定时钟或本地服务。
运行 gofmt、vet 和相关测试；涉及共享状态时追加 -race，涉及解析器时追加有上限的 fuzz。
最后再评估 API 是否需要导出。只在同一模块内部使用的能力保留在 internal，避免过早形成公共兼容负担。

审查代码时至少回答四个问题：谁拥有数据，谁允许修改，失败由谁处理，工作由谁停止。Go 的垃圾回收只解决不可达内存回收，不会替你关闭文件、取消请求、等待 goroutine 或恢复被覆盖的数据。只要其中一个问题没有答案，就先缩小函数或包的边界。

本篇最重要的能力是“理解 Seq 与 Seq2 的 yield 协议”。不要用注释替代可执行约束：能由类型表达的就交给类型，能由构造或验证表达的就返回错误，能由测试观察的就保存回归用例。示例扩展到 StudyTasks 时，还要保持领域包不导入命令行、文件和 HTTP 细节。

八、验证策略与复盘

验证分为静态、动态和故障三层。静态层检查格式、模块图和分析器；动态层用正常输入证明结果；故障层主动制造取消、权限、损坏数据、超时或竞态。一次测试通过只能说明执行过的路径符合断言，不能证明所有输入都安全，因此需要让每条关键契约至少对应一个成功用例和一个反例。

建议保存下面的复盘记录：

项目	需要记录的证据
版本	`go version`、模块与 toolchain 指令
输入	最小正常值、零值、边界值和非法值
状态	调用前后数据、资源和 goroutine 的所有者
输出	返回值、错误链、stdout/stderr 与日志字段
失败	第一个失败点、清理动作和可恢复状态
工具	实际运行的 test、race、vet、benchmark 或 build 命令

完成验证后，用另一份干净临时目录重跑，不读取开发机的用户配置、缓存数据或真实网络。若测试只能按特定顺序成功，就说明状态隔离仍不完整。若为了让测试通过必须长时间 sleep，应改用 channel、WaitGroup、context 或可注入时钟表达确定的同步条件。

本篇可以用以下目标做验收：编写能尊重提前停止的迭代器；组合过滤、映射和收集操作；使用 slices 与 maps 的迭代器接口。把它们逐项转成命令输出或断言，而不是写成“人工看起来正确”。当实现与预期不符时，先保存最小失败样例，再调整设计。

发布前再做一次反向审查：从调用方而不是实现内部出发，写出一个完全不知道具体类型和文件布局的使用示例；从故障点出发，假设进程在每个 I/O 之后被取消；从升级出发，假设下一版改变字段或默认值。若调用方必须知道未公开细节、故障会留下无法判断的状态，或升级只能覆盖旧数据，契约就还不完整。把这三个场景加入测试或文档，比继续增加抽象更有价值。

最后检查示例能否被复制到一份最小程序独立运行，所有导入、错误处理和清理是否完整。教学代码可以省略与主题无关的界面，却不能省略会改变正确性的 context、Close、边界检查或同步。对为了篇幅省略的部分要明确标注，不能让读者把伪代码误当成生产承诺。

九、StudyTasks 实践

为任务仓储提供按状态遍历的 iter.Seq[Task]，消费者找到第一项后提前停止。加入计数器证明生产者没有继续扫描，并与直接返回排序切片的 API 比较快照、一致性和重复遍历语义。

完成本节后，不要只保存代码或 SQL。请同时保存执行命令、关键输出和失败案例；学习笔记真正有价值的部分，是能够说明输入、状态变化、输出以及失败后的恢复方式。

十、常见错误

忽略 yield 返回 false，消费者退出后仍继续生产
假定 map 键迭代器会提供稳定顺序
没有说明序列能否重复遍历或是否观察实时状态
为错误和取消设计隐式全局通道
把所有简单切片循环改成复杂惰性管道

十一、练习与自测

实现 Take 迭代器并证明它会向上游传播停止。
比较直接循环、slices 函数和迭代器过滤的基准。
设计一个可返回错误的行读取序列并说明消费契约。
把 maps.Keys 的结果稳定排序后生成快照测试。

自测时应在干净的临时目录或临时数据库中重新执行，而不是依赖上一节遗留的状态。如果结果与预期不同，先记录实际输出，再缩小问题范围。

十二、官方资料

版本行为与二手文章不一致时，以本系列固定版本的官方文档、命令输出和可重复测试结果为准。

上一篇：函数值、闭包、泛型与约束下一篇：文件、JSON、正则与时间