Go iter 怎样给 Seq2 设计两个值的 yield 约定

为 Go iter.Seq2 设计 yield 约定，需要先给两个参数定义稳定含义，再把回调返回的 bool 单独解释为“是否继续”。例如 iter.Seq2[int, Job] 可以表示“原切片索引、任务值”；bool 不是第三个数据值，也不是默认的错误标志。每次调用 yield 提供一对值，收到 false 就停止迭代。

Seq2 常用于键值对或索引值对，但类型参数名 K、V 不强制第一项一定是 map 的键。API 文档还需要交代顺序、过滤后的索引、能否重复遍历，以及数据是副本还是共享引用。下面使用原创任务列表演示，代码未在本机编译运行。

官方地址：https://pkg.go.dev/iter

两个值是数据约定，bool 是继续信号

Seq2 的核心类型是 func(yield func(K, V) bool)。外层序列函数没有返回数据列表，而是把每一对数据交给回调。通常用 for k, v := range seq 消费时，编译器提供 yield；直接调用 seq 时，也可以由调用方自己提供回调。

两个值也可以设计成“任务、错误”，但那是另一个需要明确说明终止方式的业务协议，不是 Seq2 自动赋予的规则。只有一个数据值时，优先用 Seq；存在三个互相关联字段时，通常把它们放进一个结构体，不必为了套用 Seq2 随意丢失字段。

明确原始索引和过滤后序号的区别

本文的 Job 只有 Name 与 Open 两个字段。OpenJobs 过滤 Open 为 false 的任务，第一个值仍取 sourceIndex：它定位的是输入切片中的位置。比如中间跳过关闭任务后，索引可以不连续。

如果消费者需要“第几个未关闭任务”，那应另设计数器并在文档中称为过滤后序号，不能让同一个索引参数一会儿表示来源位置，一会儿表示结果排名。只有名称 Seq2[int, Job] 还不足以让调用方猜出这个区别。

实现可提前停止的 Seq2

下面完整示例需要 Go 1.23 及以上，项目语言版本也需允许 range-over-function。代码既展示 range 消费，也展示直接传回调；两种消费方法遵守同一停止约定。

package main

import (
    "fmt"
    "iter"
)

type Job struct {
    Name string
    Open bool
}

// OpenJobs按切片顺序提供未关闭任务；第一个值是原切片索引，不是过滤后序号。
// 此迭代器可重复遍历，但不创建快照，遍历期间调用方不得并发修改jobs。
func OpenJobs(jobs []Job) iter.Seq2[int, Job] {
    return func(yield func(int, Job) bool) {
        for sourceIndex, job := range jobs {
            if !job.Open {
                continue
            }
            // false表示消费者不再需要后续元素，应退出整个迭代器。
            if !yield(sourceIndex, job) {
                return
            }
        }
    }
}

func main() {
    jobs := []Job{
        {Name: "准备提纲", Open: true},
        {Name: "归档旧稿", Open: false},
        {Name: "整理插图", Open: true},
        {Name: "补充说明", Open: true},
    }
    seq := OpenJobs(jobs)
    for sourceIndex, job := range seq {
        fmt.Println(sourceIndex, job.Name)
        if sourceIndex == 2 {
            break // 编译器提供的yield将返回false，迭代器负责停止。
        }
    }
    // 可直接调用序列函数；这里仅演示消费一个元素后主动停止。
    seq(func(sourceIndex int, job Job) bool {
        fmt.Println("仅取一项:", sourceIndex, job.Name)
        return false
    })
}

按示例逻辑，第一次遍历应取得原索引 0 与 2 对应的任务，在索引 2 处 break，不再取得后面的“补充说明”。第二次直接调用 seq，应重新从输入开头取得一个未关闭任务。这是预期语义说明，并不是本文的运行日志。

if !yield(...) { return } 不能省略。消费者 break 后，编译器合成的 yield 返回 false，继续调用它违反 range 协议。嵌套循环实现中也应退出整个迭代器，而不是只 break 最里层循环后，又在外层继续提供值。

旧版本使用回调，不冒充相同语法

iter 包与对迭代器函数使用 range 的能力由 Go 1.23 提供。更早的工具链不能通过简单删除 import 就获得这种循环语法。如果暂时不能升级，可以公开传统的回调函数，保留双值和 bool 语义。

// 旧版本可采用显式回调；这里Job沿用上文声明，不使用iter包或range函数语法。
func WalkOpenJobs(jobs []Job, visit func(int, Job) bool) {
    for sourceIndex, job := range jobs {
        if job.Open && !visit(sourceIndex, job) {
            return // 同样遵守false停止的契约。
        }
    }
}

这是回调接口片段，Job 沿用前面的类型。调用方显式调用 WalkOpenJobs 并传入 visit，它不是旧版本里的 iter.Seq2，也不能直接写成 range WalkOpenJobs 的形式。保持业务契约一致，比假装语法兼容更清楚。

记录重入、所有权和资源边界

OpenJobs 的闭包捕获了切片描述符，没有深复制输入。每次调用会重新遍历捕获的切片范围，但元素内容仍可能受到外部修改影响，不能声称它是创建时的快照，也不要在遍历期间并发修改共享数据。Job 在本例中按值传递；若以后加入切片、map 或指针字段，值复制也不等于深复制。

不要保存编译器提供的 yield，等外层迭代函数返回后再从 goroutine 调用。序列函数应在自己的调用范围内提供元素，消费者提前停止后完成必要清理再返回。来自不可回退数据流的一次性序列，应专门写明可否继续、可否重遍历，不能照搬本例的行为。

如果迭代器内部获得了文件等资源，应明确由谁关闭，以及提前停止时如何清理；仅换成 Seq2 不会自动解决这些问题。本文示例没有外部资源，不虚构资源释放效果，也不声称函数迭代器必然比切片或 channel 更快。

第一个值一定必须能作 map 的键吗？

不是。Seq2 的两个类型参数约束都是 any；是否能作为 map 键，是消费端用途的额外约束。

不用第一个值时怎么写？

在循环变量位置用下划线忽略，例如 for _, job := range seq。只声明一个变量会接收第一个值，不能假定它自动变成第二个值。

yield 返回 false 后还能清理吗？

可以完成迭代器自身的必要清理并返回；不能再调用 yield 提供后续元素。停止提供值与释放自己拥有的资源并不矛盾。

参考文档：https://pkg.go.dev/iter、https://go.dev/ref/spec#For_range、https://go.dev/doc/go1.23。