【Spring Boot】ユーザーにやさしいエラーメッセージの出し方

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

新人

「Spring BootでWebアプリを作っているんですけど、たまに英語のエラーページが出てしまって、何が起きたのか分かりません…」

先輩

「それはSpring Bootが標準で用意しているエラーページですね。ちゃんと設定すれば、もっと分かりやすいエラーメッセージを表示できますよ。」

新人

「えっ、自分でメッセージってカスタマイズできるんですか？」

先輩

「もちろん。まずはエラーメッセージの基本から確認して、Spring Bootでどう扱われるか見ていきましょう。」

1. エラーメッセージとは？HTTPステータスコードの基本

Webアプリケーションでは、何か問題が発生するとサーバーから「エラーメッセージ」が返されます。このメッセージは、ユーザーに状況を伝えるための重要な情報です。特にSpring BootでWebアプリケーションを開発する際は、正しくエラー処理をしてわかりやすく表示することが重要です。

代表的なエラーコードには以下のようなものがあります：

404エラー：指定したページやファイルが見つからない場合に表示されます。
500エラー：サーバー内部で予期しない例外が発生したときに表示されます。

これらのエラーメッセージは、ユーザーが「何が起きたのか」を把握する手がかりとなります。しかし、初期設定のままだと英語で表示されることが多く、初心者のユーザーには不親切です。

そのため、Spring Bootではこれらのエラー表示を独自の画面に変更して、ユーザーにやさしいメッセージを出すことが推奨されます。

2. Spring Bootでエラー画面が表示されるタイミングとは？

Spring Bootでは、例外がスローされたり、HTTPリクエストに対応するリソースが見つからなかったりすると、自動的にエラー画面が表示されます。これには、以下のようなケースがあります。

@Controllerのメソッドで例外が発生したとき
URLに対応するコントローラが見つからないとき
バリデーションや処理の途中でエラーが起きたとき

例えば、存在しないページにアクセスした場合、Spring Bootはデフォルトで「Whitelabel Error Page」という英語の画面を表示します。これはSpring Bootが標準で用意している簡易的なエラーページです。

しかしこのままではユーザーにとって不親切です。次回以降の記事では、これを日本語でわかりやすく表示する方法や、独自のHTMLページを使ったカスタマイズ方法なども紹介していきます。

実際に、存在しないURLにアクセスしたときの表示例は次のようになります。


Whitelabel Error Page

This application has no explicit mapping for /error, so you are seeing this as a fallback.

There was an unexpected error (type=Not Found, status=404).

このような表示では、初心者のユーザーには原因が伝わりにくいため、独自に「わかりやすい日本語の説明」を用意することが大切です。次回以降では、error.htmlというファイルを使って、このエラーページをカスタマイズする方法も解説していきます。

3. Spring Bootで独自のエラーページ（error.html）を作成する方法

Spring Bootでは、デフォルトで英語のエラーページが表示されますが、ユーザーにとってやさしいアプリケーションにするためには、独自のエラーページを用意するのが望ましいです。ここでは、HTML形式でエラーを表示する方法を紹介します。

まず、src/main/resources/templatesディレクトリにerror.htmlというファイルを作成します。このファイルは、Spring Bootが自動的に読み込んで表示してくれます。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>エラーページ</title>
</head>
<body>
    <h1>申し訳ありません。</h1>
    <p>予期しないエラーが発生しました。</p>
    <p>しばらくしてからもう一度お試しください。</p>
</body>
</html>

上記のように、エラー内容を難しい表現にせず、ユーザーに安心感を与える文言で構成するのがポイントです。ここではThymeleafを利用していますが、テンプレートエンジンを使わずに静的なHTMLとしても問題ありません。

このerror.htmlを用意することで、500エラーやその他の予期しないエラーが発生したときに、英語ではなく日本語でユーザーに伝えることができます。

4. 特定のステータスコードごとにエラーメッセージを変える方法

Spring Bootでは、エラーページを1つだけでなく、ステータスコードごとに用意することもできます。たとえば404エラー用にはerror/404.html、500エラー用にはerror/500.htmlというように、テンプレートファイルを分けて作成できます。

まずは404エラー用のHTMLを用意してみましょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>ページが見つかりません</title>
</head>
<body>
    <h1>お探しのページは見つかりませんでした</h1>
    <p>入力したURLが間違っているか、ページが削除された可能性があります。</p>
</body>
</html>

次に、500エラー用のページも作っておきましょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>サーバーエラー</title>
</head>
<body>
    <h1>内部エラーが発生しました</h1>
    <p>現在システムに問題が発生しています。しばらくしてから再度お試しください。</p>
</body>
</html>

これらのファイルはsrc/main/resources/templates/errorディレクトリに配置します。Spring Bootはステータスコードに応じて自動的に該当するテンプレートを表示します。

このようにすることで、エラーの種類ごとに最適なメッセージをユーザーに届けることができ、ユーザビリティの向上につながります。

5. コントローラー側で例外をキャッチして表示を制御する方法（@ExceptionHandlerの活用）

Spring Bootでは、コントローラーレベルで特定の例外を捕捉して、専用の画面を表示することも可能です。これには@ExceptionHandlerアノテーションを使います。

以下は、NullPointerExceptionが発生した際にerror/custom-errorを表示する例です。


@Controller
public class SampleController {

    @GetMapping("/sample")
    public String sample() {
        String text = null;
        int length = text.length(); // NullPointerExceptionが発生
        return "sample";
    }

    @ExceptionHandler(NullPointerException.class)
    public String handleNullPointerException() {
        return "error/custom-error";
    }
}

この例では、例外が発生してもアプリケーション全体が停止することなく、指定されたHTML（custom-error.html）を表示できます。

テンプレートファイルはsrc/main/resources/templates/error/custom-error.htmlに配置します。例として以下のような内容にすると良いでしょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>エラーが発生しました</title>
</head>
<body>
    <h1>処理中に問題が発生しました</h1>
    <p>予期しないエラーが発生したため、処理を中断しました。</p>
</body>
</html>

@ExceptionHandlerを使うことで、より細やかなエラー制御が可能になります。特に入力チェックや処理フローで例外が発生する可能性がある場面では、個別に対応することで、ユーザーにとって安心できる案内が実現できます。

6. エラーメッセージを日本語で表示する方法（メッセージプロパティの活用）

Spring Bootで「ユーザーにやさしいエラー画面」を作るには、表示されるメッセージを日本語にしてわかりやすくすることが大切です。そのために便利なのが、messages.propertiesというファイルです。

このファイルは、アプリケーション内のメッセージを一元管理するために使用され、バリデーションメッセージや例外メッセージのカスタマイズにも活用できます。

まず、src/main/resources配下にmessages.propertiesというファイルを作成します。ここに、表示したい日本語のメッセージを設定します。


error.required=この項目は必須です。
error.server=予期しないサーバーエラーが発生しました。しばらくしてからお試しください。
error.notfound=指定されたページは見つかりませんでした。

次に、HTMLのテンプレート側でThymeleafを使ってメッセージを呼び出します。


<p th:text="#{error.notfound}">ページが見つかりませんでした</p>

このように設定しておくと、HTMLファイル内で共通のメッセージを簡単に呼び出せるようになり、メッセージの変更も一元管理できます。

日本語のプロパティファイルを用意することで、アプリケーション全体で一貫性のあるエラーメッセージを提供することができ、ユーザーの混乱を防げます。

7. ユーザーにとってわかりやすい文言のポイント（専門用語を避けるなど）

ユーザーにやさしいエラー画面を作る上で、最も重要なのは「言葉選び」です。技術者にとっては当然の用語でも、一般のユーザーにとっては意味不明な場合があります。たとえば「サーバー内部エラー」や「ステータスコード500」などは、初心者には伝わりにくい表現です。

そのため、以下のように具体的かつ親しみやすい文言に言い換えることが有効です：

「500 Internal Server Error」 → 「システムに問題が発生しました。時間をおいて再度お試しください。」
「404 Not Found」 → 「お探しのページが見つかりませんでした。URLをご確認ください。」
「Validation Error」 → 「入力内容に誤りがあります。もう一度ご確認ください。」

また、メッセージの文末に「ご迷惑をおかけして申し訳ありません」といった一言を添えることで、よりやさしい印象を与えることができます。

システムの内部事情やエラーコードの詳細を表示するのではなく、ユーザーの立場に立って「何をどうすればよいか」が伝わるメッセージを心がけると良いでしょう。

さらに、同じ言葉でも書き方や順序によって受ける印象が変わるため、できるだけ丁寧でやさしい表現を選ぶことが重要です。

8. やさしいエラーメッセージがユーザー体験を良くすることの重要性

アプリケーションにおいて、エラーが起きないのが理想ですが、実際にはどんなシステムでも例外や不具合は発生します。だからこそ、その時に表示される「エラーメッセージ」が、ユーザーにとって大切な体験の一部になります。

例えば、突然英語でエラーが表示された場合、ユーザーは混乱し、操作をあきらめてしまうかもしれません。逆に、「ご不便をおかけしています。しばらくしてからお試しください」といったやさしい日本語で案内されれば、不安を減らすことができます。

また、技術的な情報を省略しすぎると、逆にサポートに連絡する際に困ることもあります。そのため、詳細はこちらというリンクで技術情報を別画面にまとめたり、ログIDを表示して問い合わせ時に使えるようにしたりといった工夫も有効です。

やさしいエラーメッセージの設計は、ユーザーとの信頼関係を築くうえで非常に重要です。エラー画面を「開発者が隠したいもの」ではなく「ユーザーを導く案内板」として考えると、どんなメッセージを表示すべきかが自然と見えてきます。

Spring Bootでは、テンプレートや例外処理を活用することで、比較的簡単にこうしたエラー画面を整備することが可能です。ぜひ本記事を参考に、ユーザーにやさしいエラー画面の実装にチャレンジしてみてください。