Spring Bootでのエラーハンドリングの基本を学ぼう｜初心者でもわかる例外処理の仕組み

Spring Bootでのエラーハンドリングの基本を学ぼう

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

新人

「Spring Bootで開発しているときに、エラーが出ると画面に赤い文字がずらっと表示されるんですが、これってそのままでいいんですか？」

先輩

「それは『例外』っていうエラーだね。そのままにしておくと、ユーザーに内部の仕組みが見えてしまって危ないんだ。だから『エラーハンドリング』をしてあげる必要があるんだよ。」

新人

「なるほど…。でも、エラーハンドリングって具体的に何をするんですか？」

先輩

「よし、それじゃあSpring Bootでのエラーハンドリングの基本的な考え方と、Controllerでの例外処理の流れを順番に見ていこうか。」

1. エラーハンドリングとは？なぜ必要なのか

プログラムで何か問題が起きたときに処理が止まってしまう現象を「例外（Exception）」と呼びます。たとえば、存在しないIDのデータを取得しようとしたときや、数値の変換が失敗したときなどです。

このようなとき、何も対策をしていないと、ユーザーには英語の長いエラー画面がそのまま表示されてしまい、非常に不親切な印象を与えてしまいます。

そこで必要になるのが「エラーハンドリング（例外処理）」です。これは、エラーが発生したときの動作をあらかじめ定義しておくことで、処理を途中で止めずに安全に流れを制御する仕組みです。

特にWebアプリケーションでは、エラーが発生した場合でもユーザーに見せるメッセージを整えたり、エラー用のHTML画面を表示するようにしたりすることで、信頼性の高いアプリケーションになります。

「Spring Boot エラーハンドリング」では、このような処理を@ExceptionHandlerなどの仕組みを使って実現できます。

2. Spring Bootにおける基本的なエラー処理の流れ

Spring Bootでは、例外が発生すると通常は「Whitelabel Error Page」と呼ばれるデフォルトのエラーページが表示されます。しかし、これを開発者が任意にカスタマイズすることが可能です。

まず基本的なControllerでの例外処理方法として、@ExceptionHandlerを使った書き方を見てみましょう。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.ui.Model;

@Controller
public class SampleController {

    @GetMapping("/error-demo")
    public String throwError() {
        // 故意に例外を発生させる
        throw new RuntimeException("意図的な例外です");
    }

    @ExceptionHandler(RuntimeException.class)
    public String handleRuntimeException(RuntimeException ex, Model model) {
        model.addAttribute("errorMessage", ex.getMessage());
        return "errorPage";
    }
}

この例では、/error-demoというURLにアクセスすると意図的にRuntimeExceptionが発生します。その例外を@ExceptionHandlerで捕まえて、エラーメッセージを表示用のHTMLに渡す仕組みです。

このように、Controllerの中で@ExceptionHandlerを使うと、対象となる例外が発生したときに専用の処理を実行できます。これにより、単なるエラー画面ではなく、ユーザーに分かりやすい説明を表示することが可能になります。

Spring Bootではこうした基本的な「Controller 例外処理」が非常に簡単にできるため、初心者でも扱いやすい構成となっています。

もちろんこのあと、より大きなプロジェクトになると共通の例外処理をまとめる方法も出てきますが、まずは1つのController内で完結する書き方から慣れていくのがよいでしょう。

3. @ExceptionHandlerを使ったエラーハンドリングの方法

Spring Bootでは、@ExceptionHandlerを使って、特定の例外が発生したときにその処理を定義することができます。これは、Controller内で例外が発生した際に、別のHTMLページに遷移させたり、エラーメッセージを表示させたりするのにとても便利です。

たとえば、次のようにNullPointerExceptionが発生したときに、errorPageというHTMLテンプレートにメッセージを渡す例を見てみましょう。


@Controller
public class ErrorDemoController {

    @GetMapping("/null-error")
    public String throwNull() {
        String data = null;
        int length = data.length(); // NullPointerExceptionが発生
        return "index";
    }

    @ExceptionHandler(NullPointerException.class)
    public String handleNullPointer(NullPointerException ex, Model model) {
        model.addAttribute("errorMessage", "ヌルポインター例外が発生しました：" + ex.getMessage());
        return "errorPage";
    }
}

このように@ExceptionHandlerで対象の例外クラスを指定し、引数に例外オブジェクトとModelを受け取ることで、エラーメッセージをHTMLへ渡すことができます。

この方法を使えば、予期しない例外に対しても親切なエラーメッセージを表示することができ、ユーザーにとって分かりやすいアプリケーションになります。

4. カスタム例外クラスの作成と使い方

プロジェクトが大きくなってくると、Javaがもともと持っている例外クラスだけでは足りなくなる場面が出てきます。そんなときには、自分でオリジナルの「カスタム例外クラス」を作成して使うことができます。

ここでは、ユーザーが見つからなかったときに使うUserNotFoundExceptionという例外クラスを作成してみましょう。


package com.example.demo.exception;

public class UserNotFoundException extends RuntimeException {
    public UserNotFoundException(String message) {
        super(message);
    }
}

このように、RuntimeExceptionを継承したクラスを作れば、独自のエラーメッセージを投げることができます。次に、この例外を使ってControllerで処理を行ってみます。


@Controller
public class UserController {

    @GetMapping("/find-user")
    public String findUser(@RequestParam("id") int id, Model model) {
        if (id != 1) {
            throw new UserNotFoundException("ユーザーが見つかりませんでした（ID：" + id + "）");
        }
        model.addAttribute("userName", "太郎");
        return "userDetail";
    }

    @ExceptionHandler(UserNotFoundException.class)
    public String handleUserNotFound(UserNotFoundException ex, Model model) {
        model.addAttribute("errorMessage", ex.getMessage());
        return "errorPage";
    }
}

UserNotFoundExceptionが投げられると、@ExceptionHandlerで指定したメソッドが呼び出され、エラー画面に遷移します。このように「カスタム例外クラス」を使えば、より明確で整理されたエラー処理が実現できます。

特に実際の業務アプリケーションでは、「Spring カスタム例外クラス」を使った設計が標準的ですので、ぜひ覚えておきましょう。

5. エラー発生時に表示するHTML画面の作成（Thymeleaf）

Spring Bootでは、Thymeleafというテンプレートエンジンを使ってHTML画面を構築できます。エラーが発生したときに表示する画面も、通常の画面と同じようにテンプレートとして作成します。

以下は、エラーメッセージを表示するためのerrorPage.htmlのサンプルです。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>エラーが発生しました</title>
</head>
<body>
    <h2>エラーが発生しました</h2>
    <p th:text="${errorMessage}">ここにエラーメッセージが表示されます。</p>
    <a href="/">トップページへ戻る</a>
</body>
</html>

th:text="${errorMessage}"の部分がポイントです。これは、ControllerでModelに渡したerrorMessageという変数の内容を画面に表示する記述です。

このテンプレートをsrc/main/resources/templates/errorPage.htmlに配置しておけば、例外発生時に自動でこの画面が使われます。

ユーザーにとっては、突然のエラーでも親切なメッセージとナビゲーションが表示されることで、安心して操作を続けられるようになります。

こうした「Spring Boot エラーハンドリング」の一連の流れを理解することで、実践的なWebアプリケーションの構築力がぐっと高まります。

6. 共通のエラーハンドリングをまとめる方法（@ControllerAdviceの使い方）

ここまでの例では、例外処理を各Controllerごとに記述してきましたが、プロジェクトが大きくなると複数のControllerで同じようなエラーハンドリングを繰り返すことになります。

そこで役立つのが@ControllerAdviceという仕組みです。「Spring エラー共通処理」を実現するための機能で、アプリケーション全体に対して共通の例外処理を定義することができます。

以下に@ControllerAdviceを使ったサンプルコードを紹介します。


package com.example.demo.advice;

import com.example.demo.exception.UserNotFoundException;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public String handleUserNotFound(UserNotFoundException ex, Model model) {
        model.addAttribute("errorMessage", ex.getMessage());
        return "errorPage";
    }

    @ExceptionHandler(Exception.class)
    public String handleOtherExceptions(Exception ex, Model model) {
        model.addAttribute("errorMessage", "想定外のエラーが発生しました：" + ex.getMessage());
        return "errorPage";
    }
}

このように、@ControllerAdviceを付けたクラスに@ExceptionHandlerを定義すると、すべてのControllerで発生した例外を一括して処理することができます。

「Spring ControllerAdvice」は保守性の高い設計につながるため、実践開発では非常によく使われます。初心者の方も慣れてきたら、ぜひこの構成にチャレンジしてみましょう。

7. よくあるエラーとその原因・解決方法

Spring Bootで開発をしていると、初心者の方がつまずきやすいエラーがいくつかあります。ここでは代表的なものを紹介し、その原因と対策を解説します。

■ 404ページが表示されない

画面に「Whitelabel Error Page」が表示され、404 Not Foundとなる場合、考えられる原因は以下のとおりです：

コントローラのパスが間違っている
HTMLテンプレートが存在しない、または配置場所が誤っている
メソッドに@GetMappingや@PostMappingが付いていない

まずは、ControllerのURLパスが正しいか確認し、テンプレートファイルがresources/templates内に正しく置かれているかチェックしましょう。

■ @ExceptionHandlerが呼ばれない

例外処理を定義したはずなのに、指定したHTMLに遷移しないケースもよくあります。以下の点を確認してください：

例外のクラスが@ExceptionHandlerの対象と一致しているか
Controllerに@Controllerアノテーションが付いているか
テンプレートのファイル名がreturnの文字列と一致しているか

とくに多いのが、例外クラスの継承関係のミスです。たとえばNullPointerExceptionに対してExceptionで処理してもよいですが、より具体的なクラスでマッピングすると確実です。

■ errorPage.htmlが表示されない

return文で"errorPage"と指定しても、テンプレートが表示されない場合は、以下を見直してみましょう：

ファイル名がerrorPage.htmlであるか
ファイルがsrc/main/resources/templates配下に存在するか
HTMLの構文エラーがないか

とくにテンプレートの配置場所を間違えると、Spring Bootはテンプレートとして認識できません。

8. 実践で使うときのポイントと注意点

最後に、実際の現場で「Spring Boot エラーハンドリング」を使うときに意識しておきたいポイントと注意点をまとめます。

■ メッセージの見せ方に注意する

エラーメッセージは、ユーザーにとって「なぜこの画面になったのか」が分かるような内容にしましょう。内部の例外メッセージ（たとえばスタックトレースやパス情報など）をそのまま表示すると、セキュリティリスクにもつながるため注意が必要です。

■ ユーザー体験（UX）を損なわない

エラー画面を見せる場合も、ユーザーが混乱しないように「戻る」「トップページに戻る」といったナビゲーションを設けましょう。また、画面全体のデザインや文言も、通常の画面と統一感を持たせることが理想です。

■ すべての例外をキャッチしすぎない

一見便利そうに思えるException.classのハンドリングですが、すべての例外を一括で処理してしまうと、逆にデバッグが難しくなることもあります。必要な例外だけを明示的に扱い、それ以外はログに記録するなどの工夫が求められます。

■ ログ出力との併用

例外が発生したときは、画面表示だけでなく、ログにも情報を残すと便利です。特に実運用では、ユーザーからの報告だけでは原因を特定できないことも多いため、ログ出力は欠かせません。

以上のように、「Spring Boot エラーハンドリング」は単に例外を捕まえるだけではなく、アプリケーション全体の品質やユーザー体験に大きく関わる重要な要素です。初心者のうちから基本をしっかりと理解し、実践で活用できる力を身につけていきましょう。

まとめ

今回の記事では、「Spring Boot エラーハンドリング」の仕組みを基礎から応用まで幅広く学びました。例外が発生したときの挙動を制御し、ユーザーへ適切なメッセージを返す仕組みは、Webアプリケーションの安全性と信頼性を大きく左右します。とくに、初心者がつまずきやすい「Whitelabel Error Page」の扱い方、Controllerでの@ExceptionHandlerの使い方、カスタム例外クラスによる詳細な制御、Thymeleafを使ったエラー画面の構築、そしてプロジェクト全体を扱う@ControllerAdviceによる共通例外処理など、実際の開発現場で求められる知識を体系的に理解することができました。 Spring Bootでは、例外の種類ごとに適切な画面やメッセージを返せるよう細かな設定が可能で、ユーザー体験（UX）を損なわずに安全なアプリケーションを構築できます。また、カスタム例外を使うことで、業務ロジックに応じたメッセージ管理も容易になり、保守性の高いアーキテクチャを実現できます。ここでは、記事全体の理解を深めるために、エラーハンドリングと共通処理を組み合わせたサンプルコードを補足として掲載しておきます。実践的な構成を意識し、例外発生からエラーページ表示までの流れがひと目で分かる内容になっています。

サンプルプログラム：共通エラーハンドリングと個別例外の流れ

以下のコードは、「特定の例外は専用の処理を行い、それ以外は共通エラー処理に任せる」という、現場でよく使われる構成をシンプルにまとめた例です。


package com.example.demo.advice;

import com.example.demo.exception.UserNotFoundException;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.ui.Model;

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(UserNotFoundException.class)
    public String handleUserNotFound(UserNotFoundException ex, Model model) {
        model.addAttribute("errorMessage", ex.getMessage());
        return "errorPage";
    }

    @ExceptionHandler(Exception.class)
    public String handleGeneralError(Exception ex, Model model) {
        model.addAttribute("errorMessage", "予期しないエラーが発生しました：" + ex.getMessage());
        return "errorPage";
    }
}

このコードでは、UserNotFoundExceptionのみ専用のエラーメッセージを返し、それ以外は全体で共通の例外処理を行う仕組みになっています。これにより、例外の粒度を保ちながら、冗長なコードを避けつつ保守しやすい構成が実現できます。 Spring Bootのエラーハンドリングは、単なるエラー制御ではなく、安全性、ユーザー体験、開発効率をすべて向上させる重要な技術です。基礎を理解し、実践で使い続けることで、より堅牢で分かりやすいアプリケーションを作れるようになります。

新卒エンジニアと先輩社員の振り返り会話

新卒エンジニア：「Spring Bootの例外処理って、最初は難しそうに見えましたけど、仕組みを知ると便利なんですね！」

先輩社員：「そうだね。特に@ExceptionHandlerや@ControllerAdviceを使いこなすと、エラーの扱い方が一気にスマートになるよ。」

新卒エンジニア：「カスタム例外を使えば、業務内容に合わせたエラー管理ができるのも分かりました。ユーザーへの見せ方も大事なんですね。」

先輩社員：「その通り！ユーザー体験を損なわないエラー表示は、プロダクトの質に直結するからね。画面遷移やメッセージの工夫も重要なんだ。」

新卒エンジニア：「今日の内容を実践で使って、より読みやすく安全なアプリケーションを作れるように頑張ります！」

先輩社員：「しっかり覚えておけば、これからの開発でも役に立つよ。引き続き一緒に頑張ろう！」