首页 > Golang > Go问答

Go range 结构体 range over function 如何迭代

来源：17golang原创

时间：2026-10-31 18:02:59 133浏览收藏

我第一次把一个自定义容器改成 Go 1.23 的 range over function 写法时，最容易犯的错是把“结构体可迭代”理解成结构体本身可以直接放在 range 右边。实际规则更精确：结构体仍然不能直接被 range，但它可以提供一个返回迭代器函数的方法。这个方法把每个元素交给 yield，调用方就能写出自然的 for range。

官方资料：https://go.dev/ref/spec

Go 1.23 说明：https://go.dev/doc/go1.23

要让结构体支持 range over function，给它增加一个返回 iter.Seq[T] 或 iter.Seq2[K,V] 的方法；不要试图直接 range 结构体。模块的语言版本至少要是 Go 1.23。

结构体为什么要返回迭代器函数

Go 1.23 支持的不是任意函数，而是三种固定形态：func(yield func() bool)、func(yield func(V) bool) 和 func(yield func(K, V) bool)。标准库把后两种分别命名为 iter.Seq[V] 与 iter.Seq2[K,V]。

因此，自定义结构体的职责是隐藏内部存储，只把“如何依次提供元素”暴露成迭代器。调用方看到的是 book.All()，而不是结构体内部切片或链表。

RecordBook 通过 All 方法返回 iter.Seq 并由 yield 交给 for range 消费者的结构说明图 — 图1：结构说明图，展示结构体方法如何把元素交给 range over function，不是运行截图。

用 All 方法让结构体可被 range

下面的 RecordBook 仍然只是一个普通结构体；真正可被 range 的是它的 All 方法返回值。yield 返回 false 时，生产者必须立即返回，不能继续调用它。

package main

import (
    "fmt"
    "iter"
)

type Record struct {
    ID   int
    Name string
}

type RecordBook struct {
    items []Record
}

// All 把结构体内部记录暴露成 Go 1.23 的单值迭代器。
func (b RecordBook) All() iter.Seq[Record] {
    return func(yield func(Record) bool) {
        // 每次只交出一个元素；调用方 break 后 yield 会返回 false。
        for _, item := range b.items {
            if !yield(item) {
                // 停止继续访问内部数据，结束这次迭代。
                return
            }
        }
    }
}

func main() {
    book := RecordBook{items: []Record{
        {ID: 1, Name: "Go"},
        {ID: 2, Name: "range"},
    }}

    // range 的右侧是迭代器函数，不是 RecordBook 结构体本身。
    for item := range book.All() {
        fmt.Println(item.ID, item.Name)
    }
}

这个设计比直接返回一份新切片更灵活：调用方可以边消费边处理，结构体也可以在方法内部改用链表、树或计算型数据源，而不改变调用语法。

提前 break 时，yield 的返回值意味着什么

普通的 for range 中使用 break，并不只是跳出调用方代码。对 range over function 来说，编译器会让当前 yield 调用返回 false，迭代器据此停止。遍历自然结束时，生产者走完循环并返回；提前结束时，生产者应沿着 if !yield(...) { return } 这条路径收尾。

这也是为什么不能无条件连续调用 yield。如果迭代器忽略 false，它就可能在消费者已经停止后继续执行，破坏资源释放或后续状态管理。

需要键值对时改用 iter.Seq2

如果结构体迭代时同时需要索引和记录，可以返回 iter.Seq2[int, Record]。右侧函数的两个参数会对应 for index, item := range ... 的两个变量，停止协议仍然是 yield 返回布尔值。

// Entries 返回索引和记录，适合需要保留位置的调用方。
func (b RecordBook) Entries() iter.Seq2[int, Record] {
    return func(yield func(int, Record) bool) {
        // index 与 item 一起交给消费者，false 表示提前停止。
        for index, item := range b.items {
            if !yield(index, item) {
                // 不再继续读取后续记录。
                return
            }
        }
    }
}

// 调用方可以同时拿到位置和数据，并在命中条件后停止。
for index, item := range book.Entries() {
    if item.ID == 2 {
        fmt.Println(index, item.Name)
        break
    }
}