error の応用構文
実務のコードでは、エラーの種類を判別したり、既存のエラーに文脈を付け足して伝播させたり、独自の型として詳細情報を持たせたりする場面が出てきます。ここでは、error が interface として定義されている仕組みと、errors パッケージによるエラーの作成・ラップ・識別のパターンを扱います。
1. 独自エラー型の定義
Goで関数から失敗を伝えるときに使う error 型は、実は言語仕様レベルで以下のように定義された interface です(Goインタフェース 参照)。
type error interface {
Error() string
}
つまり、Error() string メソッドを持つ型はすべて error として扱えます。この仕組みのおかげで、errors.New で作った標準のエラーだけでなく、独自の型に Error() string を実装すれば、その型を独自の error として返せます。独自の型にすると、エラーに関連する情報(対象名や ID など)をフィールドとして持たせておけるのが大きな利点です。
独自エラー型は、struct に Error() string メソッドを実装して定義します。書き方は以下のとおりです。
type 独自エラー型名 struct {
フィールド名 型
// 詳細情報を必要に応じて追加
}
func (レシーバ *独自エラー型名) Error() string {
return "エラーメッセージ(フィールドの値を含めて組み立てる)"
}
次のコードでは、NotFoundError という独自の型に Name フィールドを持たせて、Error() string メソッドで Name を含むメッセージを返します。こうすることで、find から error を返しつつ「見つからなかった対象名」も一緒に呼び出し側へ伝えられるようになります。main.go を以下の内容に書き換えて保存し、go run main.go で実行します。
package main
import "fmt"
type NotFoundError struct {
Name string
}
func (e *NotFoundError) Error() string {
return fmt.Sprintf("%s が見つかりません", e.Name)
}
func find(name string) error {
return &NotFoundError{Name: name}
}
func main() {
err := find("user123")
fmt.Println(err)
}
以下のような実行結果が表示されます。
user123 が見つかりません
NotFoundError は Error() string を持つので、自動的に error インタフェースを満たし、find の戻り値 error としてそのまま返せます。追加のフィールド(Name など)に情報を持たせられるので、呼び出し側でエラーの詳細を型として扱えるようになります。
コードを解説します。
type NotFoundError struct {
Name string
}
NotFoundError は Name フィールドを1つ持つ独自の型です。この Name に「見つからなかった対象の識別子」を入れることで、エラーに詳細情報を型として持たせています。フィールドを増やせば、対象のIDだけでなくリソース種別やタイムスタンプなど、任意の情報を持たせることもできます。
func (e *NotFoundError) Error() string {
return fmt.Sprintf("%s が見つかりません", e.Name)
}
NotFoundError に Error() string メソッドを実装することで、この型は自動的に error インタフェースを満たします。特別な登録や宣言は不要で、「Error() string メソッドを持っている」というだけで error として扱えるようになるのが、Goのインタフェースの特徴です。メソッドの中では、fmt.Sprintf で Name フィールドを埋め込んだメッセージを組み立てて返します。
func find(name string) error {
return &NotFoundError{Name: name}
}
find の戻り値の型は error ですが、実際に返しているのは *NotFoundError の値です。*NotFoundError は error インタフェースを満たしているので、そのまま error として返せます。呼び出し側は error として受け取りつつ、必要になった時点で *NotFoundError として取り出して Name を参照できるようになります(型として取り出す具体的な方法は、後述の errors.As の節で扱います)。
err := find("user123")
fmt.Println(err)
find の戻り値を err で受け取り、fmt.Println で表示しています。fmt.Println は error 値を渡されたときに Error() string を自動で呼び出す仕組みになっているため、user123 が見つかりません の文字列が出力されます。
2. errors.New と fmt.Errorf
シンプルな固定メッセージのエラーは errors.New で作れます。ただし、変数の値をメッセージに埋め込みたいときに errors.New だけを使おうとすると、以下のように fmt.Sprintf でメッセージを組み立ててから渡す形になり、冗長です。
err := errors.New(fmt.Sprintf("findUser: 無効なID (%d)", id))
fmt.Errorf を使うと、fmt.Sprintf と同じ書式指定子で動的な情報を埋め込みながら、そのままエラー値を作れます。書き方は以下のとおりです。
err := fmt.Errorf("メッセージ: 値 = %v", 埋め込みたい値) // 動的な情報を埋め込んだエラー値を作る
次のコードは、findUser が不正なIDを受け取ったときに、そのIDをメッセージに埋め込んだエラーを返す例です。
package main
import (
"fmt"
)
func findUser(id int) error {
if id <= 0 {
return fmt.Errorf("findUser: 無効なID (%d)", id)
}
return nil
}
func main() {
err := findUser(-1)
fmt.Println(err)
}
以下のような実行結果が表示されます。
findUser: 無効なID (-1)
書式文字列に埋め込まれた id の値 -1 が、そのままエラーメッセージに反映されて表示されました。
コードを解説します。
return fmt.Errorf("findUser: 無効なID (%d)", id)
fmt.Errorf は fmt.Sprintf と同じ書式指定子(%d、%s、%v など)で動的な情報を埋め込みつつ、そのまま error 値を返します。errors.New(fmt.Sprintf(...)) の2段階を1つの呼び出しにまとめられるため、動的な情報を含むエラーメッセージを作るときの定番として使います。
3. エラーの識別
エラーが起きたときに、呼び出し側で「どの種類のエラーか」を判定して処理を分岐したい場面があります。例えば「ユーザが見つからないなら空の結果を返す、それ以外なら失敗として上位に伝播する」といった使い分けです。
Goでは、この識別を以下の2つを組み合わせて実現します。
エラーのラップ(fmt.Errorf + %w)は、既存のエラーを保持しつつ、その周りに関数固有の文脈(IDや入力値など)を追加した新しいエラー値を作る仕組みです。書き方は以下のとおりです。
fmt.Errorf("メッセージ ... : %w", ラップしたい元のエラー) // %w で元のエラーをラップする
エラーの判定(errors.Is)は、指定したエラーが err そのもの、または err がラップしているエラーの中に含まれているかを判定する関数です。ラップされたエラーは元のエラーと == で比較しても一致しないため、この関数を使います。書き方は以下のとおりです。
if errors.Is(err, 判定したいエラー) {
// err または err がラップしているエラーが、判定したいエラーと一致するときの処理
}
例えば以下のように == で比較しても、条件式は常に false になります。
if err == ErrNotFound { // err が ErrNotFound をラップしていても false
// ...
}
err は fmt.Errorf("... : %w", ErrNotFound) によって作られた別のエラー値で、内部に ErrNotFound を保持しているだけだからです。
| 💡 ポイント |
|---|
ラップされたエラーの判定には必ず errors.Is を使います。== で比較すると %w でラップされたエラーは別物扱いになり、意図した分岐に入らずバグの原因になります。 |
次のコードでは、ErrNotFound(ユーザが存在しない)と ErrPermissionDenied(権限がない)の2種類のエラーを判定の目印として関数の外で宣言し、findUser が id の値に応じてそれぞれを %w でラップして返します。呼び出し側では errors.Is を使って、返ってきたエラーが「ユーザが見つからない」なのか「権限がない」なのかを判定して処理を分岐します。
package main
import (
"errors"
"fmt"
)
var (
ErrNotFound = errors.New("not found")
ErrPermissionDenied = errors.New("permission denied")
)
func findUser(id int) error {
if id < 0 {
return fmt.Errorf("findUser: id=%d は権限エラー: %w", id, ErrPermissionDenied)
}
if id == 0 {
return fmt.Errorf("findUser: id=%d は見つからない: %w", id, ErrNotFound)
}
return nil
}
func main() {
err := findUser(0)
if errors.Is(err, ErrNotFound) {
fmt.Println("ユーザが見つからない場合の処理")
} else if errors.Is(err, ErrPermissionDenied) {
fmt.Println("権限エラーの処理")
}
}
以下のような実行結果が表示されます。
ユーザが見つからない場合の処理
findUser(0) は ErrNotFound をラップしたエラーを返し、呼び出し側の errors.Is(err, ErrNotFound) がラップの中を辿って一致を検知したため、対応する分岐に入って所定のメッセージが出力されました。もし findUser(-1) を呼んでいれば、ErrPermissionDenied の方の分岐に入ります。
コードを解説します。
var (
ErrNotFound = errors.New("not found")
ErrPermissionDenied = errors.New("permission denied")
)
判定の目印にする固定のエラー値を、パッケージレベル(main の外)でまとめて宣言しています。関数の中で毎回 errors.New を呼ぶと呼び出しのたびに別のエラー値になり、後で errors.Is で識別できなくなるため、このように一度だけ宣言して参照する形にします。複数のエラーを扱うときは、上記のように var (...) でまとめて書けます。
if id < 0 {
return fmt.Errorf("findUser: id=%d は権限エラー: %w", id, ErrPermissionDenied)
}
if id == 0 {
return fmt.Errorf("findUser: id=%d は見つからない: %w", id, ErrNotFound)
}
findUser は id の値に応じて、権限エラーか「見つからない」エラーかを分けて返しています。どちらも %w を使って、目印となる ErrPermissionDenied / ErrNotFound を内部に保持したまま、関数固有の文脈(id=...)を付けたエラーを返しています。
if errors.Is(err, ErrNotFound) {
fmt.Println("ユーザが見つからない場合の処理")
} else if errors.Is(err, ErrPermissionDenied) {
fmt.Println("権限エラーの処理")
}
呼び出し側では、errors.Is を順に呼び出して「どの目印がラップされているか」を判定します。ラップされたエラーでも errors.Is はラップの中を辿って比較するため、err に含まれる目印を正しく検知して該当する分岐に入ります。エラー種別を追加したい場合は、目印用の Err... 変数と、判定用の else if を追加すれば同じパターンで拡張できます。
4. 型の取り出し
「独自エラー型の定義」の節で扱ったように、独自の型に Error() string を実装すれば、追加フィールドに情報を持たせた独自エラー型として使えます。呼び出し側でそのフィールドを取り出して処理に使いたい場面では、関数から返されたエラー値の中から元の型を取り出す必要があります。
fmt.Errorf の %w でラップされたエラーは、内部に元の型を保持しています。この元の型を取り出すには、errors.As を使います。書き方は以下のとおりです。
var 受け先変数 *独自エラー型
if errors.As(err, &受け先変数) {
// err(またはそのラップ元)が独自エラー型として取り出せた場合の処理
// 受け先変数.フィールド でアクセスできる
}
次のコードでは、フォームのバリデーション失敗を表す独自エラー型 ValidationError(Field と Message の2フィールドを持つ)を定義し、validate がそれを %w でラップして返します。呼び出し側で errors.As を使ってラップの中から *ValidationError として取り出し、フィールドの詳細情報にアクセスします。
package main
import (
"errors"
"fmt"
)
type ValidationError struct {
Field string
Message string
}
func (v *ValidationError) Error() string {
return fmt.Sprintf("%s: %s", v.Field, v.Message)
}
func validate() error {
return fmt.Errorf("validate: %w", &ValidationError{Field: "email", Message: "形式が不正"})
}
func main() {
err := validate()
var verr *ValidationError
if errors.As(err, &verr) {
fmt.Printf("フィールド: %s, メッセージ: %s\n", verr.Field, verr.Message)
}
}
以下のような実行結果が表示されます。
フィールド: email, メッセージ: 形式が不正
err は fmt.Errorf でラップされていますが、errors.As がラップの中を辿って *ValidationError として取り出せたので、その Field と Message を個別に読み出して表示できました。
コードを解説します。
type ValidationError struct {
Field string
Message string
}
func (v *ValidationError) Error() string {
return fmt.Sprintf("%s: %s", v.Field, v.Message)
}
Error() string メソッドを持つ型はすべて error インタフェースを満たすため、ValidationError を独自エラー型として使えます。
func validate() error {
return fmt.Errorf("validate: %w", &ValidationError{Field: "email", Message: "形式が不正"})
}
validate は ValidationError を %w でラップして返します。返されるのは「validate: email: 形式が不正」というメッセージを持つラップ用のエラー値で、内部に *ValidationError を保持しています。呼び出し側では errors.As を使うことで、この内部の *ValidationError を取り出せます。
var verr *ValidationError
if errors.As(err, &verr) {
fmt.Printf("フィールド: %s, メッセージ: %s\n", verr.Field, verr.Message)
}
errors.As(err, &受け先変数) は、err(またはそのラップ元)が指定した型かを判定しつつ、受け先変数に取り出します。ラップされたエラーでもラップの中を辿って比較するので、err に含まれる *ValidationError を検知して verr に代入できます。取り出し後は verr.Field verr.Message のように、通常の struct フィールドとしてアクセスできます。