BindingResultの使い方と注意点｜@Validの直後に置く理由

AIによる要約

BindingResultは、@Validで検出した入力エラーをControllerで受け取るための引数です。重要なのは、@Validを付けたFormの直後に置くことです。順番を間違えると、期待通りにエラー処理できません。

新人SE

BindingResultは何となくControllerに書いています。順番ってそんなに大事なんですか？

ポンコツSE

かなり大事です。@Valid対象の直後にBindingResultを置かないと、Springがどの入力エラーを渡せばよいか判断できず、画面に戻す前に例外になることがあります。

Spring MVCで入力チェックを実装すると、@Validと一緒にBindingResultが出てきます。

新人のうちは、サンプルコードを写して動かすことはできても、なぜその順番で書くのかまでは分かりにくいです。この記事では、現場でよくレビューされる注意点に絞って整理します。

この記事のポイント

BindingResultは入力チェック結果を受け取るために使う
@Validを付けたFormの直後に置く
エラーがあればServiceへ進まず入力画面に戻す
REST APIでは例外ハンドリングに寄せる現場もある

BindingResultは入力チェック結果を受け取る

BindingResultは、FormクラスやRequest DTOに対する入力チェック結果をControllerで受け取るためのオブジェクトです。

@PostMapping("/users")
public String register(@Valid UserRegisterForm form,
                       BindingResult bindingResult) {
    if (bindingResult.hasErrors()) {
        return "users/new";
    }

    userService.register(form);
    return "redirect:/users";
}

bindingResult.hasErrors()がtrueなら、入力値に問題があります。この時点でServiceへ進まず、入力画面へ戻すのが基本です。

@Validの直後に置く理由

最重要ポイントは、BindingResultを@Valid対象の直後に置くことです。Springは、直前の検証対象に対するエラー結果としてBindingResultを扱います。

// OK
public String register(@Valid UserRegisterForm form,
                       BindingResult bindingResult,
                       Model model) {
    // ...
}

この順番なら、UserRegisterFormの入力チェック結果をbindingResultで受け取れます。

順番を間違えるとどうなるか

よくあるミスは、@ValidとBindingResultの間に別の引数を挟むことです。

// NG
public String register(@Valid UserRegisterForm form,
                       Model model,
                       BindingResult bindingResult) {
    // ...
}

この形は、入力エラーを画面で受け止める前に例外になったり、期待通りにエラーを扱えなかったりします。新人のレビューでかなり指摘されやすいポイントです。

エラーがあればServiceへ進まない

形式チェックでエラーがある状態でServiceを呼ぶと、Service側で想定外の値を扱うことになります。Controllerでは、エラーの有無を見て処理を止めます。

if (bindingResult.hasErrors()) {
    return "users/new";
}

userService.register(form);

ここでやっているのは、業務処理ではありません。入力画面に戻すための制御です。Serviceの前に止めることで、Serviceは正常な形式の入力を前提に処理しやすくなります。

Thymeleafでエラーを表示する

画面側では、Formのフィールドに紐づくエラーを表示します。

<form th:action="@{/users}" th:object="${userRegisterForm}" method="post">
  <input type="text" th:field="*{name}">
  <p th:if="${#fields.hasErrors('name')}" th:errors="*{name}"></p>

  <input type="email" th:field="*{email}">
  <p th:if="${#fields.hasErrors('email')}" th:errors="*{email}"></p>
</form>

ControllerでBindingResultを受け、同じ画面に戻すと、Thymeleaf側でエラー内容を表示できます。

REST APIでは扱い方が変わることもある

画面フォームではBindingResultを使って入力画面に戻す実装が分かりやすいです。一方、REST APIでは、入力エラーを例外ハンドラでまとめてJSONレスポンスにする現場もあります。

@PostMapping("/api/users")
public ResponseEntity<Void> create(@RequestBody @Valid UserCreateRequest request) {
    userService.create(request);
    return ResponseEntity.ok().build();
}

APIでは画面へ戻すのではなく、400エラーとエラー内容を返す設計になります。プロジェクトのエラー処理方針に合わせましょう。