🔁

Goイテレーターのエラー処理

に公開

はじめに

こんにちは、Lapi(@dragoneena12)です。

Go 1.23 からイテレーターが導入され、関数を for range で回せるようになりました。スライスやマップだけでなく、木構造やファイル、HTTPレスポンスなども for range で1件ずつ処理できると便利です。
ただし、ファイルの読み込みやネットワーク通信は途中で失敗することがあります。このときエラーをどう返すべきかについては、実は公式の推奨パターンがありません。
この内容を Gophers Meetup 2026 で発表する予定だったのですが、当日体調を崩してしまい発表できず…😭
せっかくスライドを準備したので、ブログ記事として再編してみました。

https://speakerdeck.com/dragoneena12/go-no-era-shori

復習: Goのイテレーター

まずはGoのイテレーターについて簡単に振り返ります。
Go 1.23 からは、以下のような形の関数を for range で回せるようになりました。

関数の型 受け取り方 型名(iter パッケージ)
func(yield func() bool) for range f なし
func(yield func(V) bool) for v := range f iter.Seq[V]
func(yield func(K, V) bool) for k, v := range f iter.Seq2[K, V]

yield が受け取る引数の数(0〜2個)が、for range で受け取れる変数の数に対応しています。引数が1個・2個の関数型には、標準の iter パッケージで iter.Seq / iter.Seq2 という型名が付いています。イテレーターを返す関数の戻り値には、ふつうこの型を使います。

具体例として、偶数を順に返すイテレーターを書いてみます。

func Evens(n int) iter.Seq[int] {
	return func(yield func(int) bool) {
		for i := 0; i < n; i += 2 {
			if !yield(i) {
				return
			}
		}
	}
}

for v := range Evens(10) {
	fmt.Println(v) // 0, 2, 4, 6, 8
}

yield(i) を呼ぶたびに、ループ本体が1回実行されます。ループ側で break すると yield は false を返すので、イテレーター側はそれを見て return し、反復を終えます。

実用例: 部署ツリーの配下をすべてたどる

イテレーターが便利なのは、木構造のように再帰でたどるデータも、呼び出し側からは for range だけで扱えるところです。

type Department struct {
	ID       string
	Children []Department
}

// All は配下の部署を深さ優先ですべて返す
func (d Department) All() iter.Seq[Department] {
	return func(yield func(Department) bool) {
		for _, c := range d.Children {
			if !yield(c) {
				return
			}
			for g := range c.All() {
				if !yield(g) {
					return
				}
			}
		}
	}
}
// 配下から目的の部署を探す
for dept := range root.All() {
	if dept.ID == targetID {
		found = dept
		break // 見つかった時点で走査が止まる
	}
}

使う側は探索方法などを気にせず、標準の range 記法で書くことができます。break すれば再帰の途中でもきちんと走査が止まるのもポイントです。

イテレーター自体が失敗しうるとき、エラーはどう返す?

部署ツリーのようなメモリ上のデータであれば、反復が失敗することはありません。しかし、実際には以下のような処理も for range で1件ずつ扱いたくなります。

  • ファイルを1行ずつ走査したい
    • 大きなファイルを全部メモリに載せず、1行読むごとに処理したい
  • HTTPレスポンスをストリーム的に処理したい
    • 全部届くのを待たずに、届いた分から順に処理したい

これらは途中で失敗しうる処理です。ところが、イテレーターでのエラーの返し方には公式の推奨パターンがまだなく、golang/go#71901 で議論が続いています。
ここでは、よく見られる以下の2つのパターンを紹介します。

  1. パターンA: iter.Seq2[T, error] で値とエラーを一緒に返す
  2. パターンB: Err() メソッドで、ループの後にエラーを返す

パターンA: iter.Seq2[T, error]

1つ目は、iter.Seq2 の2つ目の値としてエラーを返すパターンです。ファイルを1行ずつ読むイテレーターは以下のように書けます。

func Lines(path string) iter.Seq2[string, error] {
	return func(yield func(string, error) bool) {
		f, err := os.Open(path)
		if err != nil {
			yield("", err) // 開始前のエラーも要素として流すしかない
			return
		}
		defer f.Close()

		sc := bufio.NewScanner(f)
		for sc.Scan() {
			if !yield(sc.Text(), nil) {
				return
			}
		}
		if err := sc.Err(); err != nil {
			yield("", err)
		}
	}
}
for line, err := range Lines("app.log") {
	if err != nil {
		return err // 「流したら即 return」は暗黙の規約
	}
	fmt.Println(line)
}

呼び出し側は for v, err := range という、Goの多値返却に近い形で自然に書けます。また、要素ごとにエラーを返せるので、「この行だけパースに失敗した」といったケースも扱えます。

一方で、ファイルのオープン失敗のような反復の前後で起きるエラーの扱いが難しくなります。上の例では、オープンに失敗したエラーも1つの要素として流すしかありません。
さらに、エラーが出たら反復を止めるのか続けるのか、といった規約を型で表現できません。上の例では「エラーを流したら即 return する」ことを前提にしていますが、これはあくまで暗黙の約束です。

  • Pros
    • for v, err := range で自然に書ける
    • 要素ごとのエラーを扱える
  • Cons
    • ファイルのオープン失敗やクローズ失敗のような、前後処理のエラーの扱いが難しい
    • エラーが出たら反復を止めるのか続けるのか、といった規約を型で表現できない

パターンB: Err() メソッド

2つ目は、イテレーター自体は値だけを返し、エラーはループの後に Err() メソッドで確認するパターンです。標準ライブラリの bufio.Scanner と同じ考え方です。

type LineReader struct {
	path string
	err  error
}

func (r *LineReader) Lines() iter.Seq[string] {
	return func(yield func(string) bool) {
		f, err := os.Open(r.path)
		if err != nil {
			r.err = err
			return
		}
		defer f.Close()

		sc := bufio.NewScanner(f)
		for sc.Scan() {
			if !yield(sc.Text()) {
				return
			}
		}
		r.err = sc.Err()
	}
}

func (r *LineReader) Err() error {
	return r.err
}
lr := &LineReader{path: "app.log"}
for line := range lr.Lines() {
	fmt.Println(line)
}
if err := lr.Err(); err != nil {
	return err
}

エラーはループの後に1回確認すればよく、ファイルのオープン失敗のような反復の前後で起きるエラーも「反復が終わった理由」として自然に返せます。
以前書いたGoにはなぜ例外がないのかで紹介した、エラーを構造体に保持しておいて最後にまとめて処理する書き方に近いです。

ただし、Err() を呼び忘れてもコンパイルエラーにはなりません。エラーが起きた場合もそこでループが終了するだけなので、呼び忘れに気づきにくいのが難点です。また、要素ごとのエラーは表現できません。

  • Pros
    • エラーはループの後に1回確認すればよい
    • 反復の前後で起きるエラーも、「終わった理由」として自然に返せる
  • Cons
    • Err() を呼び忘れても気づけない
    • 要素ごとのエラーを表現できない

そもそもイテレーターを使うべきではない?

ここまで2つのパターンを紹介しましたが、そもそも「エラーが起きうる処理にはイテレーターを使うべきではない」という意見もあります。golang/go#71901 でも「iter.Seq などは失敗しない反復に限るべき」という意見が出ています。

実際、標準ライブラリには iter.Seq2[T, error] を返す API が1つもありません。os.File.ReadDir のイテレーター版を追加する提案(golang/go#70084)もありますが、エラーの返し方が決まらずまだ Open のままです。

これまで見てきたように、全体のエラーと要素ごとのエラーを両方うまく報告する方法はありません。他にも、途中で break したときの Close も失敗しうるのに、for range は結果を返さないためループの外で扱うしかありません。また、ログやトレースのための context.Context を、for range が暗黙に呼ぶイテレーターに渡す場所もありません。
標準ライブラリですらエラーを返すイテレーターの API を決めかねている、というのが現状です。

個人的な見解

議論の流れを見る限り、イテレーターでエラーを扱う方法が公式として標準化されることはなさそうです。
とはいえ、ファイルや HTTP ストリームも、扱い方を気にせず for range 文で扱えるメリットは大きいと感じています。エラーの扱い方に気をつけた上であれば、イテレーターを利用する価値は十分にあると思います。

たとえば AI エージェントの応答も、for range でストリーム的に表示できます。実際に Google の ADK for Go では、エージェントを実行する Runner.Run が iter.Seq2[*session.Event, error] を返す設計になっていますし、私たちのチームでもこの形を採用しています。

for ev, err := range agent.Run(ctx, prompt) {
	if err != nil {
		return err
	}
	fmt.Println(ev.Text)
}

まとめ

  • イテレーターを使うと、任意のコレクションをストリーム的に反復できる
  • イテレーターのエラー処理に公式の正解はなく、使わない方がいいという意見もある
  • エラーの扱いに気をつければ、イテレーターを使う価値はあると思う

イテレーターのエラー処理は、調べてみると想像以上に議論が続いているテーマでした。イテレーターのエラー処理に迷った際の参考になれば幸いです。

参考文献

https://go.dev/blog/range-functions
https://github.com/golang/go/issues/61897
https://github.com/golang/go/issues/71901
https://github.com/golang/go/issues/70084
https://sinclairtarget.com/blog/2025/07/error-handling-with-iterators-in-go/

GitHubで編集を提案
TOKIUMプロダクトチーム テックブログ
設定によりコメント欄が無効化されています