当前位置：首页 > 文章列表 > Golang > Go教程 > Go iter.Seq 怎么把分页查询包装成惰性遍历

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

来源：17golang原创 2026-09-08 04:13:37 0浏览收藏

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

要点速览

iter.Seq[T] 用 yield(T) bool 推送数据，返回 false 就代表调用方不再需要后续项。
分页游标应在迭代器内部推进；空页、重复游标和请求错误要有明确的结束策略。
需要同时传递页码、游标等信息时可用 iter.Seq2，不必把这些字段塞进业务对象。

先把一页数据变成可中断的 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 后立刻从当前迭代器返回。重复游标保护是示例中的保守策略，避免异常接口让消费端陷入无限请求；生产代码也可以改成返回错误。

Go iter.Seq 分页查询中 Page、cursor、fetch、yield 与调用方的静态边界关系图 — 图1：分页查询边界与 iter.Seq 迭代器边界的静态关系，重点看当前游标如何连接 Page、yield 和调用方。

用 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，可以把错误放进结果对象，或者让迭代器额外返回状态。

边界	建议	原因
空页但有游标	允许继续，但设置最大页数或记录异常	有些接口会暂时返回空页
重复游标	立即结束并记录错误	避免无限分页请求
调用方 break	让 yield 返回 false	停止当前迭代器和后续 fetch
请求失败	不要伪装成正常结束	调用方需要区分“没有更多”和“读取失败”

用 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，否则底层迭代器可能无法完成清理。