Go 1.23 iter.Seq 怎么设计遍历 API：何时返回切片，何时返回迭代器

给 Go 容器或者业务查询结果设计遍历接口的时候，大家以前最常用的写法就是直接返回切片。这种写法逻辑简单好理解，但调用方就算只想看前几个元素，也得等全量结果都生成完才能拿到值。Go 1.23 支持对迭代器函数使用 range，标准库提供的 iter.Seq 给 API 设计多了一个新选项：可以按需逐个把元素交给调用方，等调用方不想继续遍历的时候，生产端能立刻停下来不用跑后续多余逻辑。

接口目标：先区分你要返回的是“完整结果”还是“遍历过程”

如果函数的核心语义是“返回全部符合条件的用户”，返回 []User 往往是更合适的选择：调用方可以直接取长度、按下标访问、做排序，还能反复多次遍历。如果函数的语义是“按指定顺序逐个给到符合条件的用户”，用迭代器会和语义更匹配。核心判断标准不是哪种写法更新潮，而是调用方是不是真的需要一份完整物化的结果集合。

参数和返回值：用 iter.Seq 表达单值序列

Go 官方定义 iter.Seq[V] 是接收单个元素值的函数类型。普通容器遍历只需要逐个返回单值的话，方法返回类型直接写 iter.Seq[T] 就行；如果是键值对或者索引加值的遍历场景，就用 iter.Seq2[K, V]。调用方后续写遍历逻辑的时候，还是用大家熟悉的 for range 语法。

package users

import "iter"

type Store struct {
    items []string
}

func (s Store) All() iter.Seq[string] {
    return func(yield func(string) bool) {
        for _, name := range s.items {
            if !yield(name) {
                return
            }
        }
    }
}

调用方用起来和遍历切片的写法几乎没有区别。这里的 All 只是返回一个序列遍历规则，不会立刻生成全新的结果切片；等循环执行过程中调用方主动终止的时候，break 会让 yield 返回 false，生成元素的一端必须立刻终止逻辑。

for name := range store.All() {
    if name == "admin" {
        break
    }
}

错误模型：不要把错误偷偷藏在返回元素里

普通的 iter.Seq 只负责传递单个元素值；如果遍历过程中很可能出错误，API 设计的时候就要提前明确错误的返回位置。行业里比较稳妥的做法是返回序列加错误的组合，也就是返回 iter.Seq2[T, error]，或者把遍历前可能失败的准备工作提前做完，单独返回 error。两种方案都可行，核心要求是调用方能在循环逻辑里清晰区分“已经没有更多元素了”和“遍历过程出了错误”两种状态。

func (s Store) Names() iter.Seq2[string, error] {
    return func(yield func(string, error) bool) {
        for _, name := range s.items {
            if !yield(name, nil) {
                return
            }
        }
    }
}

for name, err := range store.Names() {
    if err != nil {
        break
    }
    _ = name
}

兼容策略：新增接口就好，不要直接换掉旧接口

已经发布的公共库如果之前就提供了返回切片的遍历方法，直接把返回类型改成 iter.Seq[T] 会让所有老调用方都编译失败。更平稳的过渡方式是保留原来的切片方法，在文档里明确说明它返回的是一份完整快照，再新增返回 All() iter.Seq[T] 或者语义更明确的遍历方法。等调用方根据自己的实际需要慢慢迁移之后，再评估旧接口要不要继续维护。

• 在模块依赖声明和文档里明确标注最低支持 Go 1.23 版本。
• 测试用例要覆盖完整遍历、空序列、循环提前退出三种常见场景。
• 遍历逻辑持有文件、锁或者网络资源的话，要在文档里写清楚资源的生命周期，必要的时候提供手动终止的方式。
• 不要为了硬凑迭代器特性，把原本很简单的小切片接口写得过度复杂，调用方的使用体验永远优先。

常见问题

iter.Seq 一定比返回切片更省内存吗？

不一定。它只是提供了按需生成元素的可能性，实际内存占用的效果还是要看数据源本身和调用方会不会提前终止遍历。如果内部逻辑已经提前把完整切片生成好了，只是换个返回类型，并不会自动减少这部分内存开销。

为什么 yield 的返回值必须做判断处理？

返回 false 代表消费方已经不需要后续的元素了。要是还继续生成多余的值，就违反了迭代器的约定，还可能浪费 I/O、CPU 资源，或者长时间持有不需要的外部资源。

什么场景下不应该引入迭代器？

当数据总量很小、调用方普遍需要反复访问或者排序、又或者团队当前项目还没升级到 Go 1.23 版本的时候，返回切片的写法通常更容易读懂和后续维护。

选择返回切片还是返回 iter.Seq，本质是做一次 API 语义层面的选择：前者交付的是一份完整的结果集合，后者交付的是一份可以中途终止的遍历过程。先想清楚调用方大多会怎么消费这份数据，再选逻辑最简单、边界最清晰的接口方案就好。