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


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通り試しました。
- 送信キーを確認する。 開発者ツールのNetworkで該当のPOSTを選び、PayloadのForm Dataに
quantityがあるか確認します。quantitiyならHTMLのnameをquantityへ直します。キー自体がなければ、入力欄にnameがあり、disabledになっていないか確認します。nameがありdisabledになっていないreadonlyの入力欄は送信されます。 - Formの値と変換エラーを比べる。 キーが
quantityなら、form.getQuantity()とerrors.getFieldError("quantity")を確認します。quantity=twoの場合、Formの値は1のままで、エラーのgetCode()はtypeMismatch、getRejectedValue()は送信されたtwoです。 - 描画で読む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版
アプリを作った後に、DIやDB更新の仕組みを調べる。
DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。
- Springで小さなWebアプリを作ったことがある
- DIやトランザクションの仕組みを確認したい
Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ
@ModelAttributeは、Formクラスと画面入力をつなぐ重要な仕組みです。GETでは画面へFormを渡し、POSTでは入力値をFormへ詰める流れで理解しましょう。
値が入らないときは、難しい原因を疑う前に、Form名、フィールド名、setter、画面側のth:fieldを確認するのが現場では近道です。



