Go iter.Seq 怎么把分页查询包装成惰性遍历

分页查询最容易写成“循环请求所有页面，再拼成一个大切片”。这样做简单，但调用方如果只需要前 20 条，后面的页面仍然会被读取。Go 1.23 引入的 iter.Seq 可以把分页过程包装成惰性序列：调用方每消费一项，迭代器才继续向当前分页接口取数据；break 或筛选器返回停止信号后，后续页面不会再请求。

先把一页数据变成可中断的 iter.Seq

先约定分页结果和查询函数。这里的 NextCursor 为空表示没有下一页，空字符串也不应该被当成下一次请求的有效游标。

package pager

import "iter"

type Page[T any] struct {
	Items      []T
	NextCursor string
}

type PageFetcher[T any] func(cursor string) (Page[T], error)

func Pages[T any](fetch PageFetcher[T]) iter.Seq[T] {
	return func(yield func(T) bool) {
		cursor := ""
		seen := map[string]struct{}{}
		for {
			// 同一个游标再次出现，说明服务端分页没有继续向前推进。
			if _, exists := seen[cursor]; exists {
				return
			}
			seen[cursor] = struct{}{}

			page, err := fetch(cursor)
			if err != nil {
				return // 真实项目可改为带错误状态的 Seq2 或外层结果对象。
			}
			for _, item := range page.Items {
				if !yield(item) {
					return // 调用方 break 或筛选器停止时，不再请求下一页。
				}
			}
			if page.NextCursor == "" {
				return
			}
			cursor = page.NextCursor
		}
	}
}

这个包装的关键不在泛型，而在控制边界：fetch 只在消费循环推进到下一页时调用，yield 返回 false 后立刻从当前迭代器返回。重复游标保护是示例中的保守策略，避免异常接口让消费端陷入无限请求；生产代码也可以改成返回错误。

用 for range 消费，按需读取并提前停止

调用方不需要知道页码，也不需要管理游标。下面的循环只取前两条符合条件的记录；当 break 执行时，yield 会返回 false，包装函数随即结束。

seq := Pages(func(cursor string) (Page[Order], error) {
	// cursor 由分页接口解释，首次请求使用空游标。
	return client.ListOrders(cursor, 50)
})

count := 0
for order := range seq {
	// 过滤逻辑放在消费端，未命中的记录仍只消费当前已取到的页面。
	if order.Status != "paid" {
		continue
	}
	store(order)
	count++
	if count == 2 {
		break // break 会让迭代器收到停止信号，不会主动拉下一页。
	}
}

要注意“惰性”不等于“请求完全不会发生”。第一次进入 range 就会请求第一页；如果第一页没有命中记录，迭代器仍会继续读下一页。若业务需要把请求错误传回调用方，不要悄悄丢弃 err，可以把错误放进结果对象，或者让迭代器额外返回状态。

用 iter.Seq2 保留页码，再组合筛选结果

如果审计、日志或排序需要知道每条记录来自第几页，可以把页码和记录一起推送。Seq2[int, T] 仍然是惰性的，但它把附加信息留在迭代器协议中，不改变 Order 结构。

func PageRows[T any](fetch PageFetcher[T]) iter.Seq2[int, T] {
	return func(yield func(int, T) bool) {
		cursor, pageNo := "", 1
		for {
			page, err := fetch(cursor)
			if err != nil {
				return // 需要传错时，改用带 error 字段的结果类型。
			}
			for _, item := range page.Items {
				if !yield(pageNo, item) {
					return // 页码与记录一起停止，不会继续取下一页。
				}
			}
			if page.NextCursor == "" {
				return
			}
			cursor = page.NextCursor
			pageNo++
		}
	}
}

for pageNo, order := range PageRows(fetchOrders) {
	// pageNo 可写入日志，order 仍保持原有业务类型。
	logPage(pageNo, order.ID)
}

Seq2 适合“键和值”或“页码和记录”这类成对数据；如果调用方最终只关心记录，可以在外层重新包装为 iter.Seq[T]，也可以直接在 range 中忽略页码。需要手动逐项拉取时使用 iter.Pull，并在提前结束时调用返回的 stop，否则底层迭代器可能无法完成清理。

常见问题

iter.Seq 会自动把所有分页数据缓存起来吗？

不会。它默认边取边推送，是否缓存取决于你的 fetch 实现和调用方是否主动收集成切片。

为什么项目能导入 iter，却不能 range seq？

通常是模块的语言版本低于 Go 1.23。检查 go.mod 的 go 指令；语言特性和工具链版本都要满足要求。

只用 iter.Seq，什么时候需要 iter.Pull？

普通遍历优先用 for range；当两个序列需要逐项对齐，或调用方本身就是“调用 next 取一条”时，再用 iter.Pull，并确保调用 stop。

把分页查询包装成 iter.Seq 后，游标推进、提前停止和业务消费各自有了清晰边界。先把错误传播策略定下来，再决定是否用 Seq2 附带页码或来源信息，通常比把所有页面一次性读入内存更容易控制。