Springのフォーム入力チェックを完全解説！BindingResultの使い方を初心者向けに紹介

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

新人

「先輩、Springでフォームを作ったんですが、入力ミスがあってもエラーがうまく表示されないんです…」

先輩

「ああ、それはバリデーションとBindingResultの使い方がポイントだね。入力チェックはちゃんと設定した？」

新人

「たぶん、@Validは付けたと思います。でも、何か足りないかも…」

先輩

「よし、それなら一緒にフォームのバリデーションとBindingResultの基本を見ていこう！」

1. 入力フォームにおけるバリデーションとは？

Webアプリケーションでは、ユーザーが入力する値に誤りがないかを確認するための「入力チェック（バリデーション）」が重要です。たとえば、名前が空欄だったり、年齢に文字列が入力されたりした場合、サーバー側で正しく処理できません。

Springでは、@Validや@NotNull、@Sizeなどのアノテーションを使って、エラーを自動的に検出できます。これにより、入力されたデータが条件に合わないと、エラーメッセージを表示したり、再入力を促すことができます。

たとえば、次のようにバリデーションを設定します。


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

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

    @Size(min = 4, max = 12, message = "ユーザーIDは4文字以上12文字以下で入力してください")
    private String userId;

    // getter, setter 省略
}

このようにしておけば、入力が不正なときに自動的にエラーが検出されます。

2. なぜSpringでBindingResultを使う必要があるのか？

BindingResultは、Springでフォームバリデーションを行う際に非常に重要な役割を果たします。入力チェックに失敗したとき、そのエラー情報を受け取るために使います。

新人

「@Validを付ければ、バリデーションが動くんですよね？それだけじゃダメなんですか？」

先輩

「@Validだけだと、エラーが発生したときに自動的に例外（400エラー）になっちゃうんだ。フォームに戻してエラーを表示させたいときは、BindingResultでエラー情報を受け取る必要があるんだよ。」

たとえば、次のようにコントローラを定義します。


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

@Controller
public class UserController {

    @GetMapping("/form")
    public String showForm(Model model) {
        model.addAttribute("userForm", new UserForm());
        return "form";
    }

    @PostMapping("/form")
    public String submitForm(@Valid @ModelAttribute UserForm userForm, BindingResult bindingResult, Model model) {
        if (bindingResult.hasErrors()) {
            return "form";
        }
        return "success";
    }
}

BindingResultは、@Validのすぐ後に記述する必要があります。この順番を間違えると、Springがバリデーション結果を正しく受け取れなくなるので注意しましょう。

実際のHTMLフォームでは、エラーを表示するための記述も行います。以下は、Thymeleafでの例です。


<form action="#" th:action="@{/form}" th:object="${userForm}" method="post">
    <div>
        <label>名前：</label>
        <input type="text" th:field="*{name}" />
        <div th:if="${#fields.hasErrors('name')}" th:errors="*{name}">名前のエラー</div>
    </div>
    <div>
        <label>ユーザーID：</label>
        <input type="text" th:field="*{userId}" />
        <div th:if="${#fields.hasErrors('userId')}" th:errors="*{userId}">IDのエラー</div>
    </div>
    <button type="submit">送信</button>
</form>

このようにすれば、ユーザーが入力ミスをしたときに、画面上にエラーメッセージを表示することができます。

新人

「なるほど、BindingResultでエラーを受け取れば、フォームに戻して表示できるんですね！」

先輩

「そのとおり！フォームエラー処理をきちんと実装するためには、入力チェックとBindingResultの連携がポイントなんだ。」

3. BindingResultを使ったControllerの基本的な書き方

Springでは、フォームから送信されたデータをサーバー側で受け取る際、BindingResultを使って入力チェックの結果を受け取ります。フォームに入力ミスがあった場合、hasErrors()メソッドでエラーの有無を確認し、再度フォーム画面に戻してエラーメッセージを表示できます。

ここでは、名前とユーザーIDを入力する簡単なフォームを例に、Controllerでのバリデーション処理の基本形を示します。


@Controller
public class UserController {

    @GetMapping("/form")
    public String showForm(Model model) {
        model.addAttribute("userForm", new UserForm());
        return "form";
    }

    @PostMapping("/form")
    public String submitForm(
        @Valid @ModelAttribute("userForm") UserForm userForm,
        BindingResult bindingResult,
        Model model) {

        if (bindingResult.hasErrors()) {
            return "form";
        }

        // 入力チェックが成功した場合の処理
        return "success";
    }
}

@ModelAttributeにはフォーム名を指定し、BindingResultは@Validの直後に置きます。順番が逆になると、Springはバリデーションエラーを検知できませんので注意してください。

このように記述することで、Springはバリデーションの結果をBindingResultに格納し、開発者がフォームエラーを自由に扱えるようになります。

4. フォームで入力エラーがある場合の処理の流れとコード例

それでは、フォームで入力ミスがあった場合の処理の流れを具体的に見ていきましょう。Springのフォーム処理では、以下のステップでエラー処理が行われます。

フォーム送信時に@Validが自動的にバリデーションを実行
結果がBindingResultに格納される
bindingResult.hasErrors()でエラーの有無をチェック
エラーがあれば元のフォームに戻り、エラーメッセージを表示
エラーがなければ成功画面や処理へ遷移

次に、Thymeleafを使って画面側でのエラーメッセージ表示を行うコード例を紹介します。


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

    <div>
        <label>ユーザーID：</label>
        <input type="text" th:field="*{userId}" />
        <div th:if="${#fields.hasErrors('userId')}" th:errors="*{userId}">ユーザーIDの入力エラー</div>
    </div>

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

このようにth:errorsを使えば、入力エラーがある場合にエラーメッセージを自動で表示できます。SpringとThymeleafを組み合わせることで、エラーチェックを視覚的にわかりやすくユーザーに伝えることができます。

新人

「もしエラーがなかったら、次の画面に進むって感じなんですね？」

先輩

「そのとおり。エラーがあるときはフォームを再表示、ないときはsuccess.htmlなどの画面に遷移するというのが基本の流れだね。」

また、フォームに戻す際にも、元の入力値をそのまま残すことができるため、ユーザーにとっても使いやすい画面になります。これもSpringのバリデーションとBindingResultの連携によるメリットのひとつです。

さらに、フォームエラー処理の中で必要に応じてログを出力したり、ログインユーザーの情報と組み合わせてバリデーションロジックを追加したりすることもできます。

このように、SpringのBindingResultを正しく使えば、フォームにおける入力ミスやエラーに柔軟に対応でき、ユーザーにもわかりやすいUIを提供できます。

5. 入力エラーをHTML画面に表示する方法（Thymeleafの例）

SpringとThymeleafを組み合わせることで、BindingResultが保持している入力エラーを画面上にわかりやすく表示することができます。特にth:errorsとth:ifを使えば、個別のフィールドに対するエラーメッセージの表示が簡単に実装できます。

次のHTMLフォームは、ユーザーの「名前」と「ユーザーID」に対して入力チェックを行い、エラーがある場合はそれぞれのフィールドの下にエラーメッセージを表示します。


<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="userId">ユーザーID：</label>
        <input type="text" id="userId" th:field="*{userId}" />
        <div th:if="${#fields.hasErrors('userId')}" th:errors="*{userId}">IDエラー</div>
    </div>

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

ここでのポイントは、th:if="${#fields.hasErrors('フィールド名')}"でエラーの有無を確認し、th:errorsでその内容を表示している点です。これにより、ユーザーがどの入力欄にミスがあるのかを視覚的に伝えることができ、ユーザー体験が大幅に向上します。

6. よくある失敗とトラブルの対処法（BindingResultが無視されるなど）

Springのフォーム開発において、BindingResultを使っているのにバリデーションエラーが正しく動作しないといったトラブルは初心者によく見られます。ここでは、よくあるミスとそのトラブルシューティングの方法を紹介します。

① BindingResultの順番が間違っている

最も多いのが、@ValidとBindingResultの順番の誤りです。Springでは、@Validの直後にBindingResultを記述しなければなりません。下記はNGな例です。


// NGな例（BindingResultの位置が後ろすぎる）
@PostMapping("/form")
public String submitForm(@ModelAttribute UserForm userForm, Model model, @Valid BindingResult bindingResult) {
    // バリデーションが機能しない
}

必ず@Validの直後にBindingResultを記述しましょう。

② @ModelAttributeの指定がない、または名前がずれている

Thymeleafのth:objectと、Controllerの@ModelAttributeで指定する名前が一致していないと、データが正しくバインドされません。たとえば、HTML側でth:object="${userForm}"と書いた場合、Controller側も次のように記述します。


@PostMapping("/form")
public String submitForm(@Valid @ModelAttribute("userForm") UserForm userForm, BindingResult bindingResult) {
    ...
}

③ バリデーション対象のクラスにアノテーションが付いていない

@NotBlankや@Sizeなどのアノテーションが未記入だと、当然バリデーションは発動しません。以下のように、正しくアノテーションを設定しているか確認しましょう。


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

    @Size(min = 4, max = 12, message = "ユーザーIDは4〜12文字で入力してください")
    private String userId;
}

これらのポイントを押さえることで、入力エラーが正しく検出され、スムーズなフォーム開発が行えるようになります。