Go iter.Seq 怎么把自定义集合接入 range

如果你的集合内部是切片、链表或树，但又想让调用方写出 for v := range collection.All()，可以把 All 定义为返回 iter.Seq[T]。关键不是把集合改成切片，而是遵守 yield(T) bool 回调约定：每次交出一个值；收到 false 后立刻停止生产。

在 Go 1.23 及以上，iter.Seq[T] 就是连接自定义集合和 range 的标准形状。集合负责调用 yield，调用方负责用 range、break 或 return 决定是否继续。

先把自定义集合暴露成 iter.Seq

先做一个最小的泛型集合。它可以继续用切片保存数据，但调用方不需要知道这个实现细节。All 返回一个闭包，闭包收到 range 提供的回调后，再逐项调用。

package main

import (
    "fmt"
    "iter"
)

type Bag[T any] struct {
    values []T
}

// All 把集合元素暴露为标准的 push iterator。
func (b Bag[T]) All() iter.Seq[T] {
    return func(yield func(T) bool) {
        for _, value := range b.values {
            // false 表示消费方已经停止，不能再调用 yield。
            if !yield(value) {
                return
            }
        }
    }
}

func main() {
    bag := Bag[string]{values: []string{"api", "cache", "worker"}}
    for value := range bag.All() {
        fmt.Println(value)
    }
}

这里没有手写索引，也没有把内部切片直接返回。以后把 Bag 换成树结构，只要 All 仍返回同样的 iter.Seq[T]，消费端代码可以保持不变。

yield 返回 false 时必须停止

range 并不是把函数当普通函数调用一次就结束，而是为它合成一个 yield。循环体每完成一次，yield 通常返回 true；循环执行 break 或因为 return 离开时，yield 会返回 false。

因此下面的提前停止是安全的：

for value := range bag.All() {
    // 找到目标后结束消费，生产者会收到 false。
    if value == "cache" {
        break
    }
    fmt.Println(value)
}

生产者收到 false 后必须从当前迭代函数返回。继续调用 yield 会违反迭代器契约；官方文档明确说明，yield 在返回 false 后再次调用属于错误。这个判断也适用于你在 Seq 内部包了一层过滤、权限判断或资源清理的情况：每一层都要把 false 向上返回。

升级旧模块时先确认语言版本

如果代码提示 range 表达式类型不支持函数，先看 go.mod，不要急着改回手写回调。范围函数是 Go 1.23 引入的语言能力，模块的 go 指令至少应为 1.23：

# 将当前模块的语言版本调整到支持 range over function 的版本
go mod edit -go=1.23

# 查看模块声明，确认 go 指令没有仍停留在旧版本
go env GOMOD
sed -n '1,5p' go.mod

这不是把工具链版本和模块语言版本混为一谈：本机可能安装了更高版本 Go，但模块仍可能按旧语言规则编译。团队升级时应把 go.mod 改动和 CI 的编译矩阵一起提交。

别把所有迭代器都当成可重复读取

返回 iter.Seq 的方法通常可以每次调用重新遍历；但流式读取文件、网络或消息的迭代器可能是 single-use。它们停止后未必能从头再来。接口注释要明确这一点，调用方也不要默认第二次 range 还能拿到相同数据。

如果消费端需要逐个拉取而不是使用 range，可以考虑 iter.Pull，但要在不再消费时调用返回的 stop。这属于另一种 pull 形状，不要为了方便把所有 Seq 都转换成 goroutine。

相关问题

iter.Seq 和 iter.Seq2 有什么区别？

Seq 每次交出一个值，Seq2 每次交出两个值，适合键值对或索引和值。

为什么 All 方法通常返回 iter.Seq？

统一返回类型后，调用方不必记住某个集合是直接可 range 还是需要先调用方法，也方便编写通用过滤器。

Go 1.22 能不能直接写 range over function？

不能使用 Go 1.23 才加入的函数范围语法；应升级模块语言版本，或继续使用普通函数回调实现兼容版本。