Go 1.23 range over function 怎么迁移：把自定义集合改成可中断迭代器

把一个自定义集合接进 for range，以前通常要暴露切片、写回调，或者先复制一份全量结果。Go 1.23 提供了非常顺畅的迁移路径：让集合方法返回 iter.Seq[T]，调用方直接写 for value := range collection.Values() 就能完成遍历。整个过程真正需要留意的不是新语法的写法，而是 yield 返回 false 时必须立刻终止后续生产逻辑，以及项目的 go.mod 最低版本不能低于 1.23。

先看 Go 1.22 及更早版本写法为什么不够自然

假设订单服务有一个只读业务集合，内部用 map 存储所有订单。旧版本代码为了不直接暴露内部的 map 结构，最常见的实现方式是对外提供回调遍历方法：

type OrderSet struct {
	items map[int64]string
}

func (s *OrderSet) Each(fn func(int64, string) bool) {
	for id, name := range s.items {
		if !fn(id, name) {
			return
		}
	}
}

这套逻辑能跑通，但调用方的遍历语义被完全包裹在方法调用内部，没法自然地使用 range 做流程中断，也没法直接接入标准库里基于迭代器封装的各类组合函数。如果改成直接返回全量切片，又会把整批订单一次性拷贝到内存，大数量场景下很容易出现性能问题。

迁移到 iter.Seq：让集合直接返回惰性序列

Go 1.23 新增的 iter.Seq[T] 本质上是 func(yield func(T) bool)。把集合的遍历方法改成这个签名之后，遍历逻辑仍然运行在集合内部，调用方却可以直接用标准的 for range 语法来处理元素。

package orders

import "iter"

type OrderSet struct {
	items map[int64]string
}

func (s *OrderSet) Values() iter.Seq2[int64, string] {
	return func(yield func(int64, string) bool) {
		for id, name := range s.items {
			if !yield(id, name) {
				return
			}
		}
	}
}

func firstLarge(set *OrderSet) (int64, string, bool) {
	for id, name := range set.Values() {
		if id > 1000 {
			return id, name, true
		}
	}
	return 0, "", false
}

这个过程不会生成任何中间切片，全量数据不会一次性加载进内存。调用方从 Values() 拿到一对键值之后，return 或 break 操作会让运行时向迭代器传回停止信号。

提前 break 时，yield(false) 是迁移的关键边界

很多人做迁移的时候，只把 yield(id, name) 语句写进遍历逻辑，却完全忘了判断它的布尔返回值。这种情况下，就算调用方已经找到目标提前终止遍历，集合内部的逻辑还是可能继续扫描内存、读取文件或者访问数据库游标，惰性遍历本身的优势就完全没了。

func (s *OrderSet) Values() iter.Seq2[int64, string] {
	return func(yield func(int64, string) bool) {
		for id, name := range s.items {
			if !yield(id, name) {
				return
			}
		}
	}
}

如果迭代器内部还持有文件句柄、数据库游标或者临时锁，提前停止的路径里也要主动释放这些资源。让生成迭代器的函数自行用 defer 管控自己的资源边界，不要让调用方猜内部的状态逻辑。

Seq 和 Seq2 怎么选，iter.Pull 什么时候才需要

绝大多数业务场景的遍历用 Seq 或 Seq2 就完全够用了。只有当调用方必须把“取下一个元素”的逻辑交给另一个状态机处理，或者需要和旧式的逐步读取 API 做对接的时候，才考虑使用 iter.Pull。pull 模式返回的 stop 不能忽略，没遍历完就退出的时候要立刻调用释放资源。

迁移前后的兼容检查怎么做

先把模块的 go.mod 版本声明切到 Go 1.23，再做编译和测试。只在自己本机装了新版本，却让 go.mod 仍然声明旧版本号，很容易导致其他同事或者 CI 流水线编译失败。

go mod edit -go=1.23
go test ./...
go vet ./...

建议至少补充两组测试用例：第一组走完整遍历，确认元素总数量和键值对应关系完全符合预期；第二组在找到目标之后立刻执行 break，用内置计数器确认生产侧没有继续执行多余的遍历逻辑。因为 Go 里 map 的遍历顺序本身不稳定，测试逻辑不要写死元素的遍历顺序。

func TestValuesCanStopEarly(t *testing.T) {
	seen := 0
	set := &OrderSet{items: map[int64]string{10: "a", 20: "b", 30: "c"}}
	for range set.Values() {
		seen++
		break
	}
	if seen != 1 {
		t.Fatalf("seen=%d, want 1", seen)
	}
}

常见问题：迁移时最容易误判的三件事

Go 1.22 能不能编译 range over function 相关逻辑？

不能把这个迭代特性当成 Go 1.22 原生语法用。项目最低兼容版本要设置为 1.23，同时本地开发环境、CI 流水线和线上发布环境都要使用对应兼容的工具链。

iter.Seq 会不会自动把所有数据全部放进内存？

不会。标准迭代器是按需调用 yield 产出元素，会不会生成中间集合完全取决于你自己的实现；只有主动调用 slices.Collect 这类明确做收集操作的函数时，才会把全量元素拼成切片。

调用方执行 break 之后，迭代器一定会停止运行吗？

只有迭代器内部主动检查并响应 yield 返回的 false 才会停止执行。忽略这个返回值的话，内层循环还是会继续跑，做很多无意义的工作。

迁移清单

• 确认 go.mod 的最低版本声明为 1.23。
• 单值遍历场景使用 iter.Seq[T]，键值遍历场景使用 iter.Seq2[K,V]。
• 每一次 yield 操作之后都要检查布尔返回值，停止分支里主动释放内部持有的所有资源。
• 用完整遍历、提前停止、空集合三个场景的测试用例验证迁移结果。

这次版本迁移的收益不在于把旧回调换成新语法，而是把“谁控制下一个元素的产出权”和“什么时候停止遍历”变成了全社区统一的标准迭代器契约。可以先从只读、边界清晰的业务集合开始改，确认停止逻辑和资源释放都能被测试覆盖，再逐步替换旧的回调遍历实现。