バリデーションエラーと画面への表示の仕方を徹底解説！Spring初心者でも分かる入力チェック

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

新人

「Springでフォーム入力のチェックってどうやるんですか？」

先輩

「Springでは、バリデーションという仕組みを使って、入力値にエラーがないか自動でチェックすることができるよ。」

新人

「入力にエラーがあるときって、どうやって画面に表示するんですか？」

先輩

「それもSpring MVCの機能を使えば簡単に実装できるよ。まずは基本から順に説明していこう！」

1. バリデーションとは？

バリデーションとは、ユーザーが入力した値が正しいかどうかをチェックする仕組みのことです。例えば、名前が空欄ではいけない、パスワードは8文字以上でなければいけないといった条件を満たしているかどうかを確認します。

これを自動的に行うことで、サーバー側で安全にデータを扱えるようになります。バリデーションエラーを検知すれば、エラーを画面に表示してユーザーに入力の修正を促すことができます。

Springでは、Javaの標準であるBean Validationという仕組みを使って、簡単にバリデーションを組み込むことができます。

2. Springでのバリデーションの基本的な仕組み

Springでは、入力フォームと連携するクラス（フォームクラスやDTOクラス）にバリデーション用のアノテーションを付けることで、自動的に入力チェックを行うことができます。

たとえば、名前が空でないことをチェックするには@NotNullや@NotBlank、文字列の長さをチェックするには@Sizeといったアノテーションを使います。

下記は、Springプロジェクトにバリデーション機能を追加するためのGradle設定です。Pleiadesの依存関係追加画面から「validation-api」や「hibernate-validator」などを選ぶこともできます。


dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-validation'
}

そして、コントローラーの引数に@Validをつけ、BindingResultでエラーを受け取るようにします。次の章では、具体的なアノテーションの使い方を解説します。

3. バリデーションアノテーションの使い方

Springのバリデーションでは、入力内容に対して複数のアノテーションを設定できます。以下は、フォーム入力用のクラスにアノテーションを付けた例です。


import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public class UserForm {

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

    @Size(min = 8, message = "パスワードは8文字以上で入力してください")
    private String password;

    // getterとsetterは省略
}

@NotBlankは、空文字やスペースだけの文字列を許可しないアノテーションです。@Sizeは、文字数の上限や下限を指定できます。

次に、このUserFormを使って、Springのコントローラーでどのように入力チェックを行うかを見てみましょう。


import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.validation.BindingResult;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;

@Controller
public class UserController {

    @GetMapping("/form")
    public String showForm(UserForm userForm) {
        return "form";
    }

    @PostMapping("/form")
    public String submitForm(@Validated UserForm userForm, BindingResult result, Model model) {
        if (result.hasErrors()) {
            return "form"; // バリデーションエラーがある場合は入力画面に戻す
        }

        // 正常時の処理（DB登録など）
        return "success";
    }
}

@Validatedを付けたUserFormが送られてきたとき、Springは自動的にアノテーションに基づいてチェックを行います。もしエラーがあれば、BindingResultにエラー情報が格納されます。

このようにして、Springでは入力値のバリデーションと画面へのエラーメッセージの表示を効率的に行うことができます。

4. バリデーションエラーの検出方法（BindingResultの使い方）

Springでは、フォームクラスに@Validatedを付けて送信すると、入力チェックが自動で行われます。そして、バリデーションエラーがあるかどうかは、BindingResultを使って確認します。

BindingResultは、バリデーション結果を格納するためのオブジェクトで、フォームオブジェクトの直後の引数に記述する必要があります。順番が異なると正しく動作しないため注意しましょう。

以下は、実際の使用例です。


@PostMapping("/form")
public String submitForm(@Validated UserForm userForm, BindingResult result, Model model) {
    if (result.hasErrors()) {
        return "form"; // エラーがある場合は再度フォームを表示
    }

    // 正常時の処理
    return "success";
}

hasErrors()メソッドは、バリデーションエラーがあるかどうかを判定します。もしエラーがある場合は、入力画面に戻って、再度ユーザーに入力を求めます。

Springでは、このようにしてエラーの有無を簡単に判定できるため、入力チェック処理を簡潔に記述できます。

5. エラー内容をHTML画面に表示する方法

次に、バリデーションエラーの内容を画面に表示する方法を解説します。Spring BootとThymeleafを組み合わせることで、エラーメッセージをユーザーに分かりやすく表示できます。

Thymeleafにはth:errorsという属性が用意されており、特定のフォームフィールドに対して発生したエラーメッセージを表示できます。

以下は、名前とパスワードの入力欄にエラーを表示するHTMLのテンプレート例です。


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

    <div>
        <label for="password">パスワード：</label>
        <input type="password" id="password" th:field="*{password}" />
        <div th:if="${#fields.hasErrors('password')}" th:errors="*{password}"></div>
    </div>

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

th:fieldは、フォームクラスのプロパティとHTML要素をバインドするための属性です。また、th:errorsは、そのフィールドに対してバリデーションエラーが存在する場合に、該当するメッセージを表示します。

さらに、th:ifを使って、エラーがある場合のみエラーメッセージを表示するように制御しています。これにより、画面上には必要なエラーだけが表示されるようになります。

6. 入力フォームの作成方法（エラーメッセージと連携）

Thymeleafを使ったフォームでは、th:objectでフォームクラスを指定し、各フィールドに対してth:fieldでバインドを行います。これにより、コントローラーと画面側のデータ連携が簡単に実現できます。

以下は、全体的なフォーム画面のHTMLの構成例です。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>フォーム入力</title>
</head>
<body>
    <h2>ユーザー登録フォーム</h2>
    <form th:action="@{/form}" th:object="${userForm}" method="post">
        <div>
            <label for="name">名前：</label>
            <input type="text" id="name" th:field="*{name}" />
            <div th:if="${#fields.hasErrors('name')}" th:errors="*{name}"></div>
        </div>

        <div>
            <label for="password">パスワード：</label>
            <input type="password" id="password" th:field="*{password}" />
            <div th:if="${#fields.hasErrors('password')}" th:errors="*{password}"></div>
        </div>

        <div>
            <button type="submit">登録</button>
        </div>
    </form>
</body>
</html>

このように記述することで、Spring側で検出したバリデーションエラーが自動的に画面上に反映されます。Thymeleafは、Springと密接に連携できるテンプレートエンジンのため、バリデーションのエラー表示にも非常に便利です。

なお、画面の項目数が増えても、同じようにth:fieldとth:errorsをセットで使用すれば、他の入力項目にも簡単にバリデーションを追加できます。

このように、Spring MVCとThymeleafを組み合わせることで、初心者でも分かりやすく、正確にエラーメッセージを表示できる入力フォームを作成することができます。

7. よくあるバリデーションエラーの対処法

Springでバリデーションを行うと、よくあるエラーとして「空欄エラー」や「文字数制限違反」があります。こうしたエラーは@NotBlankや@Sizeなどのアノテーションを使ってチェックするのが一般的です。

たとえば、名前が空のまま送信された場合、@NotBlankで指定したメッセージが表示されます。

しかし、初心者がつまずきやすいのは「意図したアノテーションが効かない」「正しくエラーが表示されない」といった現象です。そうしたときは、以下の点を確認してみましょう。

フォームクラスに正しくアノテーションが付けられているか
コントローラーで@Validatedを指定しているか
HTML側でth:errorsを使ってエラーメッセージを表示しているか

また、数字の範囲チェックには@Minや@Max、メールアドレスの形式チェックには@Emailを使うことができます。


import jakarta.validation.constraints.*;

public class UserForm {

    @NotBlank(message = "名前を入力してください")
    private String name;

    @Size(min = 8, message = "パスワードは8文字以上で入力してください")
    private String password;

    @Email(message = "正しいメールアドレスを入力してください")
    private String email;

    @Min(value = 18, message = "年齢は18歳以上である必要があります")
    private int age;

    // getter、setterは省略
}

このように、目的に合わせたアノテーションを使うことで、さまざまな入力条件に対応することができます。