Spring Bootの@ModelAttributeとFormに値が入る仕組みを解説する記事のアイキャッチ。若手エンジニアがJava道場風の学習空間でフォーム連携を学ぶイラスト。

実装・エラー解決

Spring Bootの@ModelAttributeとは?Formに値が入る仕組みと使い方

AIによる要約

@ModelAttributeは、リクエストパラメータをFormのプロパティに結びつけ、Formを画面に渡すModelの属性にします。POSTで値が入らないときは、送られたキー、型変換の結果、Thymeleafが読むModel名の順に確認します。

新人SE
新人SE
Formクラスにいつ値が入っているのか、正直よく分かっていません。
ポンコツSE
ポンコツSE
@ModelAttributeは、リクエストのname属性とFormのプロパティを対応させて値を詰めます。画面側の名前とController側の名前を揃えるのが大事です。

Spring MVCのフォームで入力値が反映されないときは、開発者ツールで送信された名前と値を確認します。BindingResultには、送信された値をFormの型に変換できなかった場合のエラーが残ります。POSTで値が入らないときの確認手順を見る。

利用者登録の画面を例に、初回GETで部署を「開発」、利用枠を1で表示し、POSTで利用枠に abc が送られたら、入力した値と選んだ部署を残して画面を返します。初回に用意したFormと、POSTで値を受け取るFormが同じ名前を使うところを追います。

この記事のポイント

  • @ModelAttributeはFormとリクエスト値を結びつける
  • 初回GETで使うFormと、選択肢などの表示用データをModelへ入れる
  • POSTでは入力値がFormへバインドされる
  • Form名とフィールド名のずれが値が入らない原因になる

実行用サンプル

初回GETの値と部署一覧、フォーム名が違うときの描画エラー、入力エラー時の再表示を確認できます。 ソース全文、JUnitの検証コード、curlの実行ファイル、pom.xml、READMEを収録しています。JDK 17とMaven 3.9系で mvn test を実行します。Spring Boot 3.5.16のサンプルです。

@ModelAttributeはFormをModelに載せる

@ModelAttributeは、Formクラスを画面へ渡したり、リクエストパラメータからFormへ値を詰めたりするために使われます。

UserRegistrationController.java の抜粋。選択肢と初回表示のFormを用意する

    @ModelAttribute("departments")
    public List<Department> departments() {
        return DEPARTMENTS;
    }

    @GetMapping("/users/new")
    public String newUser(Model model) {
        model.addAttribute("userRegisterForm", new UserRegisterForm("", "DEV", 1));
        return "users/new";
    }

GET /users/new では、氏名が空欄、部署は「開発」DEV、利用枠は1のFormを userRegisterForm としてModelに入れます。メソッドにつけた @ModelAttribute("departments") はGET・POSTの両方に部署一覧を載せるため、エラーで戻った画面でも選択肢が残ります。

POSTでは入力値がFormへ入る

POST時には、画面の入力欄のnameとFormクラスのプロパティ名が対応し、値が詰められます。

UserRegisterForm.java の抜粋。フォームの入力項目と制約

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

    @NotBlank(message = "部署を選択してください")
    private String department;

    @NotNull(message = "利用枠を入力してください")
    @Min(value = 1, message = "利用枠は1以上で入力してください")
    private Integer seatLimit;

たとえばブラウザーが name=Sato&department=OPS&seatLimit=2 をPOSTすると、Spring MVCは UserRegisterForm の各プロパティに値を設定します。利用枠の 2 は Integer に変換されます。

Thymeleaf側の名前が重要

画面側では、th:objectとth:fieldでFormとフィールドを紐づけます。

new.html の抜粋。入力欄、部署の選択肢、項目別のエラー表示

<form method="post" th:action="@{/users}" th:object="${userRegisterForm}">
    <label>氏名 <input type="text" th:field="*{name}"></label>
    <span th:errors="*{name}"></span>
    <label>部署
        <select th:field="*{department}">
            <option th:each="department : ${departments}"
                    th:value="${department.code()}" th:text="${department.label()}"></option>
        </select>
    </label>
    <span th:errors="*{department}"></span>
    <label>利用枠 <input type="text" inputmode="numeric" th:field="*{seatLimit}"></label>
    <span th:errors="*{seatLimit}"></span>
    <button type="submit">登録</button>
</form>

テンプレートの th:object="${userRegisterForm}" がModelの属性名に対応し、th:field="*{seatLimit}" が name="seatLimit" の入力欄を作ります。属性名を form に変えると、Thymeleafが userRegisterForm を見つけられず、描画に失敗します。

UserRegistrationController.java の抜粋。意図的にModel名を変えた初回GET

    @GetMapping("/demo/users/wrong-form-name")
    public String wrongFormName(Model model) {
        model.addAttribute("form", new UserRegisterForm("", "DEV", 1));
        return "users/new";
    }

値が入らないときに見るポイント

Formに値が入らないときは、Springの仕組みを疑う前に、名前の対応を確認します。

確認ポイント

  • HTMLのname属性とFormのプロパティ名が合っているか
  • th:objectの名前とModelの属性名が合っているか
  • この例のようにプロパティへ設定する場合は、Formにsetterがあるか
  • 送信されない disabled の入力欄になっていないか

初回GETで画面が開かないなら th:object とModel名を照合します。画面が開くのにPOSTの値が入らないなら、開発者ツールのForm Dataに seatLimit があるかを見ます。seatLimit=abc が送られていれば、名前ではなく整数への型変換が失敗しています。

POSTで値が入らないときは、送信キーから確認する

注文フォームで数量を2に変えて送ったのに、画面には初期値の1が戻るとします。Integer quantityの初期値を1にした短い例で、同じPOST /ordersを4通り試しました。

  1. 送信キーを確認する。 開発者ツールのNetworkで該当のPOSTを選び、PayloadのForm Dataにquantityがあるか確認します。quantitiyならHTMLのnameをquantityへ直します。キー自体がなければ、入力欄にnameがあり、disabledになっていないか確認します。nameがありdisabledになっていないreadonlyの入力欄は送信されます。
  2. Formの値と変換エラーを比べる。 キーがquantityなら、form.getQuantity()とerrors.getFieldError("quantity")を確認します。quantity=twoの場合、Formの値は1のままで、エラーのgetCode()はtypeMismatch、getRejectedValue()は送信されたtwoです。
  3. 描画で読むModel名を合わせる。 Controllerで数量が2なら、ビューに渡したFormがorderFormであることを確認します。明示した属性名orderFormをth:object="${orderForm}"で参照し、項目をth:field="*{quantity}"につなげます。Javaの引数名はformです。

OrderFormController.javaのPOSTメソッドの抜粋です。Modelの属性名は@ModelAttribute("orderForm")で指定し、その直後にこのFormのBindingResultを置きます。

@PostMapping("/orders")
public String checkQuantity(
        @ModelAttribute("orderForm") OrderForm form,
        BindingResult errors) {
    return "orders/new";
}

Spring Boot 3.5.16のMockMvcで確認した結果

  • quantity=2 → Formの数量は2、エラーなし。
  • quantitiy=2 → 名前が一致せず、数量は1、エラーなし。
  • キーなし → 数量は1、エラーなし。
  • quantity=two → 数量は1、typeMismatch。エラーにはtwoが残ります。

この比較例ではすべてHTTP 200でorders/newへ戻ります。入力が反映されたかは、Formの数量とエラーを組み合わせて判定します。

この抜粋は数量だけを比べる別の例です。上の配布ZIPの9件では、利用者登録画面の初回表示、属性名の不一致、入力エラー時の再表示などを確認できます。

BindingResultとセットで使う

入力チェックを行う画面では、@ModelAttribute、@Valid、BindingResultがセットで出てきます。

UserRegistrationController.java の抜粋。入力エラー時は同じビューを描画する

    @PostMapping("/users")
    public String register(@Valid @ModelAttribute("userRegisterForm") UserRegisterForm form,
                           BindingResult errors, Model model) {
        if (form.getDepartment() != null && !form.getDepartment().isBlank()
                && DEPARTMENTS.stream().noneMatch(department -> department.code().equals(form.getDepartment()))) {
            errors.rejectValue("department", "unknownDepartment", "一覧から部署を選択してください");
        }
        if (errors.hasErrors()) {
            model.addAttribute("showCorrectionNotice", true);
            return "users/new";
        }
        userService.register(form.getName(), form.getDepartment(), form.getSeatLimit());
        return "redirect:/users/new?registered";
    }

利用枠 abc は Integer に入らず、BindingResult にフィールドエラー typeMismatch が残ります。そのリクエストのまま users/new を描画するため、氏名 Sato、部署「運用」OPS、入力した文字列 abc とエラーメッセージが表示されます。初期値のFormでModelを上書きすると、この表示に必要な情報が失われます。

次のテストは、エラーのある画面が開くだけでなく、部署と入力文字列がHTMLに残り、登録が行われないことを確かめます。

UserRegistrationTest.java の抜粋。変換に失敗した後の表示と登録処理を検証

    @Test
    void conversionErrorRetainsSubmittedTextAndDepartment() throws Exception {
        mvc.perform(post("/users").formField("name", "Sato")
                        .formField("department", "OPS").formField("seatLimit", "abc"))
                .andExpect(status().isOk())
                .andExpect(view().name("users/new"))
                .andExpect(model().attributeHasFieldErrorCode("userRegisterForm", "seatLimit", "typeMismatch"))
                .andExpect(content().string(containsString("name=\"name\" value=\"Sato\"")))
                .andExpect(content().string(containsString("value=\"OPS\" selected=\"selected\"")))
                .andExpect(content().string(containsString("name=\"seatLimit\" value=\"abc\"")))
                .andExpect(content().string(containsString("利用枠は整数で入力してください")));
        assertThat(service.calls).isEmpty();
    }

現場では省略形にも出会う

Spring MVCでは、Formクラスの引数に@ModelAttributeが省略されているコードもあります。

UserRegistrationController.java の抜粋。規約の属性名でフォームを受け取る比較用メソッド

    @PostMapping("/demo/users/implicit")
    public String implicit(@Valid UserRegisterForm form, BindingResult errors, Model model) {
        return register(form, errors, model);
    }

この比較用メソッドでは、Spring MVCがクラス名 UserRegisterForm から userRegisterForm を属性名に選ぶため、同じテンプレートで表示できます。別名を使う画面では、明示した属性名とテンプレートの指定を揃えます。

Controllerからフォーム・画面に値が渡る仕組みを体系的に整理するなら、『Spring徹底入門 第2版』のSpring MVC章とThymeleaf章が参考になります。

書籍「Spring徹底入門 第2版」の表紙
商品画像:Amazon.co.jp
PR 入門後の参考書|Spring Framework 5向け

Spring徹底入門 第2版

株式会社NTTデータ (著), 株式会社NTTデータグループ (編集)

アプリを作った後に、DIやDB更新の仕組みを調べる。

DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。

  • Springで小さなWebアプリを作ったことがある
  • DIやトランザクションの仕組みを確認したい

Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。

当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。

この記事とあわせて読みたい

関連記事Spring Bootの@RequestParamとFormクラスの違いは?使い分けを解説 @RequestParam は単発の値を受け取るときに便利です。一方、Formクラスは画面入力や検索条件のように複数項目を1つの入力として扱いたいときに向いています。 記事を読む 関連記事BindingResultの使い方と注意点|@Validの直後に置く理由 BindingResult は、 @Valid で検出した入力エラーをControllerで受け取るための引数です。重要なのは、 @Valid を付けたFormの直後に置くことです。 記事を読む 関連記事Spring BootのFormとDTOの違い|Serviceへ渡すクラスを分ける判断 先に結論FormをServiceへ直接渡してよいかは、画面の入力契約とServiceの業務処理の契約が同じかで判断します。 記事を読む

まとめ

@ModelAttributeは、Formクラスと画面入力をつなぐ重要な仕組みです。GETでは画面へFormを渡し、POSTでは入力値をFormへ詰める流れで理解しましょう。

値が入らないときは、難しい原因を疑う前に、Form名、フィールド名、setter、画面側のth:fieldを確認するのが現場では近道です。

-実装・エラー解決
-,