新人と先輩の会話形式で理解しよう

新人

「Spring Bootで画面を作っていると、エラーが起きたときに見慣れないエラー画面が勝手に表示されるんですが、あれはどこで制御されているんですか？」

先輩

「Spring Bootでは、エラーが発生したときの動きをあらかじめ用意してくれているんだよ。」

新人

「自分ではエラー用のコントローラを書いていないのに、エラー画面が出るのが不思議で……」

先輩

「それがまさに、Spring Bootのデフォルトエラーハンドリングの仕組みなんだ。」

1. Spring Bootでエラーが起きると何が起こるのか

Spring Bootを使ってWebアプリケーションを作成していると、コントローラの処理中に例外が発生した瞬間、自動的にエラー画面が表示されることがあります。これは、Spring Boot デフォルトエラーハンドリングがあらかじめ組み込まれているためです。

例えば、URLに対応するコントローラが存在しない場合や、コントローラの処理中で例外が発生した場合、開発者が何も設定していなくても、 Spring Bootはエラー用の画面を表示します。

初心者の方は、「どこにもエラー用のHTMLを書いていないのに、なぜ画面が出るのか」と疑問に感じることが多いです。これは、Spring Bootが内部でエラー処理用の仕組みを持っており、その仕組みが自動的に動作しているためです。

Spring MVCの視点で見ると、エラーが起きた場合も一種のリクエスト処理として扱われます。通常の画面表示と同じ流れで、「エラー用の処理」が呼び出されていると考えると理解しやすくなります。


@Controller
public class SampleController {

    @GetMapping("/sample")
    public String sample() {
        int result = 10 / 0;
        return "sample";
    }
}

このようなコードでは、実行時に例外が発生します。それにもかかわらず、アプリケーションが完全に止まるのではなく、エラー画面が表示されるのは、 Spring Bootがエラーを受け止めて処理しているからです。

2. Spring Bootのデフォルトエラーハンドリングとは何か

Spring Bootのデフォルトエラーハンドリングとは、開発者が特別な設定をしなくても、エラー発生時の処理を自動で行ってくれる仕組みのことです。その中心的な役割を担っているのが、 BasicErrorController というクラスです。

BasicErrorControllerは、 Spring Bootの内部に用意されているエラー処理専用のコントローラです。エラーが発生すると、 Spring MVCの仕組みによってこのコントローラが呼び出されます。

つまり、開発者が書いた @Controller の処理で例外が処理しきれなかった場合、最終的に BasicErrorController が登場し、エラー画面の表示を担当します。これが「自分で書いていないのにエラー画面が出る」理由です。

Spring Boot デフォルトエラーハンドリングは、初心者にとって非常にありがたい存在です。最低限のエラー表示が保証されているため、まずは画面を動かしながら開発を進めることができます。一方で、この仕組みを理解せずに使い続けると、エラー処理の全体像が見えにくくなることもあります。


@Controller
public class AnotherController {

    @GetMapping("/notfound")
    public String notFound() {
        return "noPage";
    }
}

このように、意図しないエラーや未定義の画面にアクセスした場合でも、 Spring Bootは自動的にエラー処理へと制御を移します。それを支えているのが、 BasicErrorControllerを中心とした Spring Bootのデフォルトエラーハンドリングです。

次のステップでは、この BasicErrorController が Spring MVCの中でどのような位置づけにあり、どのような流れで呼び出されているのかをさらに詳しく見ていくことになります。

3. BasicErrorController の役割と位置づけ

Spring MVC エラーハンドリングを理解するうえで、 BasicErrorController の役割と位置づけを把握することはとても重要です。このクラスは、開発者が直接作成するものではなく、 Spring Boot が最初から内部に用意している特別な @Controller です。

BasicErrorController は、「アプリケーション内で最終的に処理されなかったエラー」を受け取るための受け皿として存在しています。つまり、通常のコントローラや例外処理で対応できなかった場合に、最後に必ず呼ばれる保険のような存在です。

初心者が混乱しやすい点として、「自分で書いたコントローラなのに、なぜ別のコントローラが動いているのか」という疑問があります。これは、Spring Bootがエラー専用のリクエスト先を用意し、そこに処理を引き渡しているためです。

Spring MVCの視点で見ると、 BasicErrorController も通常の @Controller と同じ扱いです。ただし、通常のURLではなく、エラー発生時に内部的に割り当てられたパスを処理します。この仕組みによって、開発者が何も設定しなくてもエラー画面が表示されます。

Spring Boot デフォルトエラーハンドリングは、開発初期段階では非常に便利ですが、「なぜそう動くのか」を知らないまま使い続けると、後から独自のエラー処理を実装する際に理解が追いつかなくなります。そのため、BasicErrorController は「最後に必ず通る場所」として意識しておくことが大切です。

4. エラーが発生してからエラー画面が表示されるまでの流れ

BasicErrorController 仕組みを理解するためには、エラー発生から画面表示までの流れを順番に追って考えることが効果的です。 Spring MVCでは、リクエスト処理は段階的に進みます。

まず、ブラウザからリクエストが送られると、 Spring MVCは対応する @Controller のメソッドを探します。そのメソッドの中で、パラメータ処理や業務処理が実行されます。この途中で例外が発生すると、処理はその場で中断されます。

次に、Spring MVCは「この例外を処理できる仕組みが用意されているか」を探し始めます。同じコントローラ内に @ExceptionHandler があれば、そこで処理が完結します。しかし、何も定義されていない場合、例外はさらに外側へと伝わっていきます。

最終的に、どこにも処理先が見つからなかった例外は、 Spring Bootが用意しているデフォルトのエラー処理ルートへと渡されます。ここで登場するのが BasicErrorController です。これが「自分で書いていないのに動く」正体です。


@Controller
public class ErrorFlowController {

    @GetMapping("/flow")
    public String flow() {
        String value = null;
        value.length();
        return "flow";
    }
}

この例では、明示的な例外処理を一切書いていません。それでもエラー画面が表示されるのは、例外が最終的に BasicErrorController に引き渡され、そこで画面表示用の処理が行われているからです。

この一連の流れを理解すると、 Spring MVC エラーハンドリングが「例外をどこで止めるか」という設計で成り立っていることが見えてきます。 BasicErrorController は、その流れの一番外側に位置しています。

5. Spring MVCの例外処理とBasicErrorControllerの関係

Spring MVCには、例外処理のための仕組みがいくつか用意されています。代表的なものが @ExceptionHandler や @ControllerAdvice です。これらは、BasicErrorController よりも手前の段階で例外を処理するための仕組みです。

@ExceptionHandler は、特定のコントローラ内で発生した例外を処理するための方法です。一方、@ControllerAdvice を使うと、複数のコントローラに共通する例外処理を定義できます。これらは「開発者が明示的に用意する例外処理」です。

それに対して BasicErrorController は、開発者が何も用意しなかった場合の最終手段として機能します。つまり、Spring MVCの例外処理は、内側から外側へ段階的に処理が移っていく構造になっています。


@Controller
public class HandlerController {

    @GetMapping("/handler")
    public String handler() {
        throw new IllegalStateException();
    }

    @ExceptionHandler(IllegalStateException.class)
    public String handleState() {
        return "error";
    }
}

この場合、例外は @ExceptionHandler で処理されるため、 BasicErrorController まで到達しません。逆に言えば、 @ExceptionHandler や @ControllerAdvice がなければ、例外は必ず BasicErrorController に流れ着きます。

初心者が混乱しやすいのは、「エラー画面が出たり出なかったりする」点です。これは、例外が途中で処理されているかどうかの違いです。 Spring Bootのデフォルトエラーハンドリングは、すべての例外を強制的に処理する仕組みではありません。

Spring MVC エラーハンドリングを正しく理解するためには、「どこで例外を処理するのか」「どこまで処理を任せるのか」という視点を持つことが大切です。 BasicErrorController は、その設計の基準点として存在しています。

次のステップでは、このデフォルトの仕組みをどのようにカスタマイズすべきか、そして実務ではどこまで任せ、どこから自分で制御するのかを考えていくことになります。

6. BasicErrorControllerに頼りすぎると起きやすい問題

Spring Boot エラー画面仕組みを学び始めた初心者にとって、 BasicErrorController はとても便利な存在です。何も設定していなくても、エラーが起きたときに最低限の画面を表示してくれるため、開発を止めずに進めることができます。

しかし、この便利さに慣れすぎると、いくつかの問題が起きやすくなります。代表的なのが、「どの画面で、どのようなエラーが起きているのかが分かりにくい」という点です。

BasicErrorController は、あくまで汎用的なエラー処理を行うための仕組みです。そのため、業務的な意味を持つエラーや、ユーザに伝えたい内容まで細かく制御することはできません。すべてのエラーが同じ流れで処理されてしまうと、原因調査や修正が難しくなります。

また、デフォルトのエラー画面に頼り続けると、「どこで例外が発生しているのか」「どの段階で処理が止まっているのか」をコードから読み取りにくくなります。これは、エラー処理が明示的に書かれていないためです。

実務では、エラーが発生した場合の挙動を把握できない状態は大きなリスクになります。 BasicErrorController はあくまで最後の受け皿であり、すべてを任せる前提で使うものではない、という意識を持つことが重要です。

7. デフォルトエラーハンドリングとカスタム例外処理の使い分け

Spring Boot デフォルトエラーハンドリングと開発者が用意するカスタム例外処理は、どちらか一方を選ぶものではありません。それぞれに役割があり、段階的に使い分けることが大切です。

学習初期や小規模な画面開発では、まずは BasicErrorController の挙動を理解し、「エラーが起きると、どこに流れていくのか」を体感することが優先されます。これを理解せずに、いきなりカスタム例外処理を書くと、全体像を見失いやすくなります。

一方で、特定の画面で想定されるエラーや、業務的に意味を持つエラーについては、コントローラ側で明示的に処理した方が分かりやすくなります。その第一歩が @ExceptionHandler です。


@Controller
public class StepController {

    @GetMapping("/step")
    public String step() {
        if (true) {
            throw new IllegalArgumentException();
        }
        return "step";
    }

    @ExceptionHandler(IllegalArgumentException.class)
    public String handleStepError() {
        return "stepError";
    }
}

このように書くことで、特定の例外は BasicErrorController に渡さず、自分で制御できるようになります。これが、デフォルトエラーハンドリングとカスタム例外処理の役割分担です。

実務では、すべての例外を最初からカスタマイズすることはほとんどありません。まずはデフォルトの動きを理解し、必要な部分だけを上書きしていく、という進め方が一般的です。

BasicErrorController は、「何も設定していないときの基準動作」として理解しておくと、その後の設計が非常に楽になります。

8. 次に学ぶべきSpring MVCのエラーハンドリング設計

Spring Bootのデフォルトエラーハンドリングを理解したあとは、より実践的なエラー処理設計へと進んでいくことになります。ここで重要なのは、いきなり複雑な仕組みに手を出さないことです。

次の学習ステップとして意識したいのが、 @ExceptionHandler を使ったコントローラ単位の例外処理です。これにより、「どの画面で、どのエラーを扱っているのか」がコード上で明確になります。

さらにその先には、 @ControllerAdvice を使った共通例外処理があります。これは、複数のコントローラにまたがるエラー処理を整理するための仕組みです。 BasicErrorController を理解していないと、この位置づけが分かりにくくなります。

また、画面設計の観点では、エラー専用ページをどのように用意するか、エラー内容をどこまで表示するか、といった設計も重要になってきます。これは、エラーページ設計というテーマにつながります。

実務では、デフォルト挙動を把握した上で、必要な部分だけを @ExceptionHandler や @ControllerAdvice で補い、最終的にユーザにとって分かりやすいエラー画面を用意します。この段階的な理解が、 Spring MVC エラーハンドリング設計の基礎になります。

BasicErrorController を出発点として、 @ExceptionHandler、 @ControllerAdvice、そしてエラーページ設計へと学習を進めていくことで、 Spring Bootのエラー処理全体を自信を持って扱えるようになります。

Spring Boot のデフォルトエラーハンドリングを理解しよう！BasicErrorControllerをSpring視点でやさしく解説