Go エラーハンドリング

利用可能なスクリプト

• scripts/check-errors.sh — エラーハンドリングのアンチパターンを検出します: err.Error() に対する文字列比較、コンテキストなしの return err、ログと返却の両立。bash scripts/check-errors.sh --help でオプションを確認してください。

Go では、エラーは値です — コードによって作成され、コードによって消費されます。

エラー戦略の選択

1. システム境界 (RPC、IPC、ストレージ)? → %v でラップして内部を隠す
2. 呼び出し元が特定の条件にマッチしている必要がある? → Sentinel またはカスタム型エラー、%w でラップ
3. 呼び出し元がデバッグコンテキストだけが必要? → fmt.Errorf("...: %w", err)
4. リーフ関数、ラップ不要? → エラーを直接返す

デフォルト: %w でラップし、フォーマット文字列の末尾に配置します。

---

コアルール

コンクリートなエラー型を返さない

エクスポートされた関数からコンクリートなエラー型を返さないこと — コンクリートな nil ポインタはインターフェース上で非 nil になる可能性があります:

// Bad: コンクリート型は微妙なバグを引き起こす可能性がある
func Bad() *os.PathError { /*...*/ }

// Good: 常にエラーインターフェースを返す
func Good() error { /*...*/ }

エラー文字列

エラー文字列は大文字で始まらないようにし、句読点で終わらないようにします。例外: エクスポートされた名前、固有名詞、または頭字語。

// Bad
err := fmt.Errorf("Something bad happened.")

// Good
err := fmt.Errorf("something bad happened")

表示されるメッセージ (ログ、テスト失敗、API レスポンス) の場合は、大文字化は適切です。

エラー時の返却値

関数がエラーを返す場合、呼び出し元は明示的にドキュメント化されていない限り、すべての非エラー返却値を不定と見なす必要があります。

ヒント: context.Context を受け取る関数は通常 error を返すべきなので、呼び出し元はコンテキストがキャンセルされたかどうかを判定できます。

---

エラーの処理

エラーに遭遇したときは、意識的に選択してください — _ で破棄しないこと:

1. 即座に処理 — エラーに対処して続行
2. 呼び出し元に返す — コンテキスト付きでオプショナルにラップ
3. 例外的な場合 — log.Fatal または panic

意図的に無視する場合: なぜかを説明するコメントを追加します。

n, _ := b.Write(p) // nil でない error を返さない

関連する並行操作の場合、errgroup を使用します:

g, ctx := errgroup.WithContext(ctx)
g.Go(func() error { return task1(ctx) })
g.Go(func() error { return task2(ctx) })
if err := g.Wait(); err != nil { return err }

インバンドエラーを回避する

エラーを知らせるために -1、nil、または空文字列を返さないでください。複数の返却値を使用します:

// Bad: インバンドエラー値
func Lookup(key string) int  // 見つからない場合は -1 を返す

// Good: 明示的なエラーまたは ok 値
func Lookup(key string) (string, bool)

これにより、呼び出し元が Parse(Lookup(key)) を書くのを防ぎます — Lookup(key) は 2 つの出力を持つため、コンパイル時エラーが発生します。

---

エラーフロー

通常のコードの前にエラーを処理します。早期のリターンはハッピーパスをインデントなしに保ちます:

// Good: エラーファースト、通常コードはインデントなし
if err != nil {
    return err
}
// 通常のコード

エラーを一度だけ処理 — ログするか返すか、両方はしない:

エラーが発生した?
├─ 呼び出し元が対処できる? → 返す (%w でコンテキスト付き)
├─ 呼び出しチェーンの最上部? → ログして処理
└─ どちらでもない? → 適切なレベルでログして続行

複雑なエラーフローを構造化するとき、ログ vs 返却の判断、ハンドル・オンスパターンの実装、または構造化ログレベルの選択については、references/ERROR-FLOW.md を読んでください。

---

エラー型

勧告: 推奨されるベストプラクティス。

呼び出し元がマッチする必要がある?	メッセージ型	使用
いいえ	static	errors.New("message")
いいえ	動的	fmt.Errorf("msg: %v", val)
はい	static	var ErrFoo = errors.New("...")
はい	動的	カスタム error 型

デフォルト: fmt.Errorf("...: %w", err) でラップします。errors.Is() には Sentinel にエスカレート、errors.As() にはカスタム型を使用します。

Sentinel エラーを定義するとき、カスタムエラー型を作成するとき、またはパッケージ API のエラー戦略を選択するときは、references/ERROR-TYPES.md を読んでください。

---

エラーラップ

勧告: 推奨されるベストプラクティス。

• %v を使用: システム境界で、ログのために、内部詳細を隠すために
• %w を使用: errors.Is/errors.As のためにエラーチェーンを保持するために

重要なルール: %w を末尾に配置します。呼び出し元が持っていないコンテキストを追加します。注釈が何も追加しない場合は、err を直接返します。

%v と %w のどちらを使うか判断するとき、パッケージ境界を越えてエラーをラップするとき、またはコンテキスト情報を追加するときは、references/WRAPPING.md を読んでください。

検証: エラーハンドリングを実装した後、bash scripts/check-errors.sh を実行して一般的なアンチパターンを検出します。次に go vet ./... を実行して追加の問題をキャッチします。

---

関連スキル

• エラー命名: Sentinel エラー (ErrFoo) またはカスタムエラー型の命名については go-naming を参照してください
• エラーテスト: errors.Is/errors.As でエラーセマンティクスをテストするときまたはエラーチェックヘルパーを書くときは go-testing を参照してください
• Panic 処理: panic とエラー返却のどちらかを判断するときまたは recover ガードを書くときは go-defensive を参照してください
• ガード句: 早期リターンエラーフローを構造化するときまたはネストを削減するときは go-control-flow を参照してください
• ログ判断: ログレベルを選択するとき、構造化ログを設定するとき、またはログメッセージに含めるコンテキストを判断するときは go-logging を参照してください