入力チェックエラーを画面に表示する方法（Thymeleaf）｜初心者でもわかるSpring MVCバリデーションの基本

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

新人

「Spring MVCでフォームの入力チェックエラーを画面に表示したいんですが、どうやって実装すればいいですか？」

先輩

「入力チェックエラーを画面に表示するには、Spring MVCのバリデーション機能とThymeleafの連携が基本です。バリデーションでエラーが検出されたら、その情報をコントローラで受け取り、Thymeleafのテンプレートに渡して表示します。」

新人

「入力チェックエラーって具体的にはどんなものですか？」

先輩

「例えば、必須入力項目が空だったり、メールアドレスの形式が正しくない場合のエラーです。これらはユーザーの誤入力を防ぎ、正しいデータだけを受け付けるために重要なんですよ。」

新人

「なるほど、Spring MVCでのバリデーションはどうやって実現するんですか？」

先輩

「Spring MVCでは、@Validatedや@Validアノテーションを使ってモデルのバリデーションを行い、その結果をBindingResultで受け取ります。BindingResultにはエラー情報が格納されていて、これを使ってエラー表示を制御します。」

新人

「具体的にコードの例とかも知りたいです！」

先輩

「はい、それは次のセクションで詳しく説明しましょう。PleiadesでGradleを使った環境、@Controllerでの実装方法をベースに解説しますね。」

1. 入力チェックエラーとは何か？基本的な概要と重要性

入力チェックエラーとは、ユーザーがフォームに入力したデータが定められたルールに合わない場合に発生するエラーのことです。例えば、必須項目が空欄であったり、数字のみ許可されている箇所に文字が入力されていたりする場合が該当します。

これらのエラーを適切に検知し画面に表示することは、ユーザーに正しい入力を促し、誤ったデータによるシステムのトラブルを防ぐために非常に重要です。Spring MVCはこうした入力チェックを簡単に実装できる仕組みを備えており、Thymeleafを使ってエラー内容を画面に表示するのが一般的です。

正しいエラー表示ができるとユーザーの操作性が向上し、Webアプリケーションの品質も高まりますので、ぜひ覚えておきたいポイントです。

2. Spring MVCでのバリデーションとエラー情報の取得方法

Spring MVCのバリデーションは、JavaのBean Validation API（JSR-380）に準拠しており、@Validatedや@Validアノテーションを使ってモデルクラスのフィールドに検証ルールを指定します。

フォームから送信されたデータは、コントローラのメソッドの引数として受け取り、バリデーションが自動的に実行されます。その結果はBindingResultオブジェクトに格納され、バリデーションエラーの有無や詳細を確認することが可能です。

以下の例は、Pleiades環境でGradle管理、@Controllerを使ったバリデーションの基本的な流れを示しています。


@Controller
public class SampleController {

    @PostMapping("/submit")
    public String submitForm(@Validated SampleForm form, BindingResult bindingResult) {
        if (bindingResult.hasErrors()) {
            // エラーがある場合は入力フォームに戻る
            return "formPage";
        }
        // エラーなしの場合は処理を続行
        return "successPage";
    }
}

このように、Spring MVCではバリデーションの結果をBindingResultで受け取り、エラーがあるかどうかをhasErrors()メソッドで判定します。ここでエラーがあれば再度入力画面へ戻し、エラーがなければ次の処理へ進みます。

3. BindingResultで取得したエラー情報をThymeleafで表示する方法

Spring MVCでフォームの入力チェックエラーが発生すると、バリデーションの結果はBindingResultに格納されます。このBindingResultに含まれるエラー情報をThymeleafのテンプレートに渡して画面に表示することが重要です。

具体的には、コントローラでBindingResultを受け取り、エラーがある場合は同じ入力画面に戻しつつ、モデルにエラー情報をセットします。Thymeleafのテンプレートでは、th:errors属性などを使って、対応するフォーム項目のエラーメッセージを簡単に表示できます。

こうすることで、ユーザーはどの項目にどのような入力ミスがあるのかを視覚的に理解しやすくなり、修正もしやすくなります。

4. Thymeleafのエラーメッセージ表示タグとその使い方の具体例

Thymeleafでは、フォームの入力チェックエラーを表示するためにth:errors属性を利用します。この属性を利用すると、対応するフィールドのエラーメッセージを自動的に表示できます。

例えば、名前入力欄のエラー表示を行うには、以下のように記述します。


<form action="#" th:action="@{/submit}" th:object="${sampleForm}" method="post">
    <label for="name">名前</label>
    <input type="text" id="name" th:field="*{name}" />
    <div th:if="${#fields.hasErrors('name')}" th:errors="*{name}" class="text-danger"></div>

    <button type="submit">送信</button>
</form>

ここで、th:field="*{name}"はフォームの入力項目とモデルのnameフィールドをバインドし、th:errors="*{name}"がその入力欄のエラーメッセージを表示します。

また、th:if="${#fields.hasErrors('name')}"でエラーが存在する場合のみエラーメッセージの要素が表示されるように制御しています。これにより、エラーがない場合は表示されず、画面がすっきりします。

このようにThymeleafのタグを利用することで、簡潔かつわかりやすくエラー表示が実装できます。

5. コントローラでのBindingResultの受け取りとモデルへのエラー情報のセット

Spring MVCのコントローラでは、バリデーション結果をBindingResultで受け取り、エラーがある場合は入力画面に戻してエラー情報をモデルにセットします。以下はPleiades環境でGradleを使用し、@Controllerで実装した例です。


@Controller
public class SampleController {

    @PostMapping("/submit")
    public String submitForm(@Validated SampleForm form, BindingResult bindingResult, Model model) {
        if (bindingResult.hasErrors()) {
            // エラー情報をモデルに追加（Thymeleafが自動的に処理するため必須ではないが、
            // 独自表示などに使う場合は有効）
            model.addAttribute("org.springframework.validation.BindingResult.sampleForm", bindingResult);
            model.addAttribute("sampleForm", form);
            return "formPage";
        }
        return "successPage";
    }
}

このコードでは、bindingResult.hasErrors()でエラーの有無を判定し、エラーがあれば同じ入力フォーム画面に戻します。モデルにはバリデーション対象のフォームオブジェクトとBindingResultがセットされ、Thymeleafがそれらを使ってエラーを表示します。

特に、ThymeleafがBindingResultを自動で参照するために、org.springframework.validation.BindingResult.オブジェクト名のキーでBindingResultをモデルに登録することが重要です。これにより、th:errorsなどの機能が正しく動作します。

以上が、Pleiades＋Gradle環境で@Controllerを使い、Spring MVCバリデーション結果をThymeleafで画面表示する基本的な流れです。

6. 入力チェックエラーをユーザーにわかりやすく伝えるためのポイント

入力チェックエラーはユーザーにとって非常に重要なフィードバックです。正しく伝えられないとユーザーはどこが間違っているのか分からず、操作ミスや離脱の原因になります。そこで、以下のポイントを押さえてエラー表示を実装しましょう。

具体的でわかりやすいメッセージ：例えば「名前を入力してください」や「メールアドレスの形式が正しくありません」といった明確な説明を心がけます。
エラー箇所の近くに表示：エラーメッセージは入力欄のすぐ近くに表示し、どの項目が問題なのか一目でわかるようにします。
視覚的な強調：エラー箇所は赤文字や枠線で強調するとユーザーに認識されやすくなります。ただし、Pleiades環境ではBootstrapは使えないため、シンプルなCSSで対応します。
複数エラーの一覧表示：複数項目でエラーがあった場合は、エラー一覧をまとめて表示するとユーザーの理解を助けます。
入力値の保持：エラー時に入力済みの値を保持し、再入力の手間を減らすことでユーザービリティを向上させます。

これらのポイントを押さえることで、ユーザーがスムーズに正しい入力を行えるようになります。

7. よくあるエラー表示のトラブルと対処法

Thymeleafでの入力チェックエラー表示では、初心者にありがちなトラブルも存在します。ここでは代表的な問題とその解決策を紹介します。

エラーが表示されない
原因として、コントローラでBindingResultをモデルに正しくセットしていない場合があります。特に、org.springframework.validation.BindingResult.オブジェクト名のキー名が正確であることを確認しましょう。
フォームの値がクリアされてしまう
エラー発生時に入力値が消えてしまうのは、モデルに再セットしていなかったり、フォームのバインドが正しく行われていないためです。th:objectでモデルをバインドし、コントローラで再セットすることが重要です。
エラーメッセージが英語のまま
Bean Validationのメッセージがデフォルトで英語の場合、日本語化用のメッセージプロパティファイルを用意してカスタマイズしましょう。
複数エラーの扱いが難しい
複数のエラーをまとめて表示する場合、Thymeleafのth:eachでエラーリストをループ処理する方法を使い、画面に一覧を表示します。

これらのトラブルは正しい設定とコードの理解で解決可能なので、落ち着いて対処してください。

8. 実践例：Thymeleafを使った入力チェックエラー表示のまとめ

最後に、Pleiades＋Gradle環境で@Controllerを使い、Thymeleafで入力チェックエラーを表示する一連の流れを実践例でまとめます。

まず、モデルクラスにバリデーションルールを設定します。


public class UserForm {

    @NotBlank(message = "名前は必須入力です")
    private String name;

    @Email(message = "メールアドレスの形式が正しくありません")
    @NotBlank(message = "メールアドレスは必須入力です")
    private String email;

    // ゲッター・セッター省略
}

次に、コントローラでバリデーションを実行し、エラー時はBindingResultをモデルにセットして入力画面に戻します。


@Controller
public class UserController {

    @PostMapping("/register")
    public String register(@Validated UserForm userForm, BindingResult bindingResult, Model model) {
        if (bindingResult.hasErrors()) {
            model.addAttribute("org.springframework.validation.BindingResult.userForm", bindingResult);
            model.addAttribute("userForm", userForm);
            return "registerForm";
        }
        // 正常処理（登録成功ページへ）
        return "registerSuccess";
    }
}

最後にThymeleafのテンプレートでは、以下のようにエラー表示を実装します。


<form th:action="@{/register}" th:object="${userForm}" method="post">
    <label for="name">名前</label>
    <input type="text" id="name" th:field="*{name}" />
    <div th:if="${#fields.hasErrors('name')}" th:errors="*{name}" class="text-danger"></div>

    <label for="email">メールアドレス</label>
    <input type="email" id="email" th:field="*{email}" />
    <div th:if="${#fields.hasErrors('email')}" th:errors="*{email}" class="text-danger"></div>

    <button type="submit">登録</button>
</form>

この構成で、ユーザーが入力ミスをした際に具体的なエラーメッセージが入力欄の近くに表示され、再入力がしやすくなります。ユーザビリティを高め、誤入力によるトラブルを未然に防ぐために非常に有効な実装方法です。

この記事で紹介したポイントや実践例を参考に、Pleiades＋Gradle環境でSpring MVCとThymeleafを使った入力チェックエラーの表示をぜひマスターしてください。