Springで複数フォームを1ページに配置する方法！ModelAttribute名とバインディングのポイント解説

1. 1ページ複数フォームの設計が必要になる場面とは？

1. 1ページ複数フォームの設計が必要になる場面とは？

Spring MVCで、1つのHTMLページ内に複数の異なるフォームを表示したいケースは意外とよくあります。たとえば「プロフィール更新フォーム」と「パスワード変更フォーム」を同じ画面に出すときなどです。

このような場面では、それぞれのフォームに異なるModelAttributeを割り当てて、コントローラ側で別々にバインド処理を行う必要があります。

2. 複数フォームを使うときの@ModelAttributeの役割

2. 複数フォームを使うときの@ModelAttributeの役割

Spring MVCでは、@ModelAttributeで指定した名前を使って、ビュー（HTML）とコントローラでデータの橋渡しをします。フォームを複数設置する場合、@ModelAttributeの名前が重複すると、バインディング時にどのフォームのデータなのか曖昧になります。

そこで、各フォームには個別の@ModelAttribute名を付けて、バインディングの衝突を防ぎます。

3. HTML側でのフォーム記述とname属性の指定

3. HTML側でのフォーム記述とname属性の指定

フォームのth:objectには、それぞれ異なるModelAttribute名を指定しましょう。以下のように書き分けます。

<form th:action="@{/profile/update}" th:object="${profileForm}" method="post">
    <input type="text" th:field="*{name}" />
    <input type="email" th:field="*{email}" />
    <button type="submit">プロフィール更新</button>
</form>

<form th:action="@{/password/change}" th:object="${passwordForm}" method="post">
    <input type="password" th:field="*{currentPassword}" />
    <input type="password" th:field="*{newPassword}" />
    <button type="submit">パスワード変更</button>
</form>

このように、フォームごとにth:objectの属性が異なっていれば、各入力項目のバインディング先が明確になります。

4. コントローラー側でのバインディング処理

4. コントローラー側でのバインディング処理

コントローラーでも、それぞれのフォームに対応する@ModelAttribute名を明示的に指定することで、意図しないデータの混在を防げます。

@Controller
public class AccountController {

    @GetMapping("/account/settings")
    public String showSettings(Model model) {
        model.addAttribute("profileForm", new ProfileForm());
        model.addAttribute("passwordForm", new PasswordForm());
        return "account/settings";
    }

    @PostMapping("/profile/update")
    public String updateProfile(@ModelAttribute("profileForm") ProfileForm profileForm, BindingResult result) {
        if (result.hasErrors()) {
            return "account/settings";
        }
        // 更新処理
        return "redirect:/account/settings?success";
    }

    @PostMapping("/password/change")
    public String changePassword(@ModelAttribute("passwordForm") PasswordForm passwordForm, BindingResult result) {
        if (result.hasErrors()) {
            return "account/settings";
        }
        // パスワード変更処理
        return "redirect:/account/settings?changed";
    }
}

ここでは、profileFormとpasswordFormがそれぞれ別の処理にバインドされるため、フォームの送信先が混在しないようになっています。

5. バリデーションを個別に実装する方法

5. バリデーションを個別に実装する方法

それぞれのフォームクラスに@Validatedや@Validアノテーションを使えば、フォームごとに別々のバリデーションルールを適用可能です。

@PostMapping("/profile/update")
public String updateProfile(@Validated @ModelAttribute("profileForm") ProfileForm profileForm, BindingResult result) {
    if (result.hasErrors()) {
        return "account/settings";
    }
    // 更新処理
    return "redirect:/account/settings?success";
}

BindingResultの位置には注意が必要で、@ModelAttributeの直後に書かなければ例外が発生します。

6. エラーメッセージの表示方法も分ける

6. エラーメッセージの表示方法も分ける

それぞれのフォームにエラーを表示したい場合も、バインド対象の名前を分けておくことで、個別のエラーブロックを出し分けできます。

<form th:object="${profileForm}">
    <div th:if="${#fields.hasErrors('*')}" class="alert alert-danger">
        <ul>
            <li th:each="err : ${#fields.errors('*')}" th:text="${err}"></li>
        </ul>
    </div>
</form>

このように、複数のModelAttributeを使う設計は、入力の分離やバリデーション、エラー表示の柔軟性につながります。

7. 複数フォームバインディングの落とし穴と対処法

7. 複数フォームバインディングの落とし穴と対処法

ありがちなミスとしては、コントローラー側でModelAttribute名を省略したり、フォームでth:objectを間違えて共有してしまうケースです。その場合、意図しないデータがバインドされたり、バリデーションが効かないなどの不具合が起こります。

それを避けるためには、以下のルールを守るのがコツです：

• 各フォームに固有の@ModelAttribute名を設定する
• フォームの送信先（action）も別々にする
• 入力モデルも別々に定義する

8. テストや確認時のチェックポイント

8. テストや確認時のチェックポイント

実装後に以下の点をチェックすると、バインディングの不具合を早期に見つけることができます。

• それぞれのModelAttributeが正しくHTMLのth:objectに対応しているか
• フォーム送信後、どちらのハンドラに遷移しているか
• バリデーションが意図通りに働いているか
• 意図しないデータのバインドが起こっていないか

特に、入力エラーがあったときに、正しいフォームだけが再表示されているかも重要です。

まとめ

まとめ

Springで複数フォームを扱う設計の考え方

本記事では、Spring MVCを使って一つの画面に複数のフォームを配置する方法について詳しく解説してきました。 Webアプリケーション開発では、プロフィール編集とパスワード変更、検索フォームと登録フォームなど、 一つのページ内で役割の異なるフォームを同時に扱う場面が多く存在します。 そのようなケースで重要になるのが、@ModelAttributeの名前設計と、 フォームごとのバインディングを明確に分離する考え方です。

Spring MVCでは、ビューとコントローラーの間でデータを受け渡す際に、 @ModelAttributeで指定した名前が重要な役割を果たします。 複数フォームを同じページに配置する場合、すべてのフォームが同じモデル名を共有してしまうと、 どのフォームの入力値なのかを判別できなくなり、バインディングエラーや意図しない動作の原因になります。 そのため、フォームごとに異なるモデルクラスとModelAttribute名を用意することが、 安定したSpring MVC設計の基本となります。

HTMLとコントローラーの役割分担

HTML側では、th:objectに正しいModelAttribute名を指定することで、 入力項目とJavaのフォームクラスが一対一で対応します。 これにより、入力値のマッピングが明確になり、可読性の高いテンプレートを維持できます。 一方、コントローラー側では、@PostMappingごとに異なるハンドラメソッドを用意し、 それぞれに対応する@ModelAttributeを受け取ることで、 フォーム送信時の処理を安全に分岐できます。

また、バリデーション処理を個別に行える点も、複数フォーム設計の大きなメリットです。 @Validatedや@Validを使うことで、 各フォームに専用の入力チェックルールを適用でき、 エラーメッセージの表示もフォーム単位で制御できます。 この仕組みにより、ユーザーにとって分かりやすく、操作しやすい画面を実現できます。

まとめとしてのサンプルプログラム

ここでは、複数フォーム設計の考え方を整理するために、 シンプルな構成のサンプルコードを改めて確認してみましょう。 それぞれのフォームが独立してバインディングされることがポイントです。

@Controller
public class SummaryController {

    @GetMapping("/sample")
    public String show(Model model) {
        model.addAttribute("formA", new FormA());
        model.addAttribute("formB", new FormB());
        return "sample";
    }

    @PostMapping("/formA")
    public String submitA(@ModelAttribute("formA") FormA formA) {
        return "redirect:/sample";
    }

    @PostMapping("/formB")
    public String submitB(@ModelAttribute("formB") FormB formB) {
        return "redirect:/sample";
    }
}

このように、ModelAttribute名、送信先URL、フォームクラスを明確に分けることで、 複数フォームであっても混乱のない実装が可能になります。 Spring MVCにおけるフォームバインディングの理解は、 中規模から大規模なWebアプリケーション開発において特に重要な知識です。