@ModelAttributeでフォームのデータを受け取る方法を完全解説！初心者でもわかるSpring MVCの基本

@ModelAttributeでフォームのデータを受け取る方法

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

新人

「Spring MVCでフォームから送信されたデータって、どうやってJavaのコードで受け取るんですか？」

先輩

「それには@ModelAttributeっていうアノテーションを使うんだよ。Spring MVCの中ではかなり基本的な仕組みだね。」

新人

「@ModelAttributeってよく見るけど、正直よくわからなくて…。何をしてくれるんですか？」

先輩

「よし、それじゃあ@ModelAttributeの役割と、フォームとの関係について順番に説明していこうか。」

1. @ModelAttributeとは？Spring MVCでの基本的な役割

@ModelAttributeは、Spring MVCの機能のひとつで、HTMLフォームから送信されたデータをJavaのクラスに自動で詰めてくれる便利なアノテーションです。

例えば、名前やメールアドレスなどの情報をHTMLフォームで入力して「送信」したとき、そのデータはContactFormのようなJavaクラスに変換されて処理されます。その自動変換（バインディング）を行うのが@ModelAttributeの役割です。

以下は、@ModelAttributeを使った基本的なコントローラの例です。


@Controller
public class ContactController {

    @PostMapping("/submit")
    public String submit(@ModelAttribute ContactForm form, Model model) {
        model.addAttribute("name", form.getName());
        model.addAttribute("email", form.getEmail());
        return "result";
    }
}

この例では、HTMLフォームで入力された「name」と「email」の値が、自動的にContactFormオブジェクトの中にセットされます。そして、コントローラ内ではそれを自由に使うことができるようになるのです。

このように、Spring MVCにおける@ModelAttributeは、HTMLフォームとJavaのFormクラスの橋渡しをしてくれる非常に重要な存在です。

2. なぜ@ModelAttributeを使うのか？フォームとの連携の基本を理解しよう

なぜ@ModelAttributeが必要なのかというと、HTMLの入力項目とJavaのプロパティを自動で結びつける（バインディング）ためです。これを手作業で行うと非常に大変ですが、Springがそれを自動でやってくれることで、コードがシンプルで読みやすくなります。

たとえば、以下のようなHTMLフォームがあるとします。


<form action="/submit" method="post">
    <label for="name">お名前:</label>
    <input type="text" id="name" name="name" /><br>

    <label for="email">メールアドレス:</label>
    <input type="email" id="email" name="email" /><br>

    <input type="submit" value="送信" />
</form>

このフォームの入力値を受け取るには、下記のようなFormクラスを用意します。


public class ContactForm {
    private String name;
    private String email;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

そして、コントローラで@ModelAttributeを使えば、Springがフォームのname属性とContactFormのプロパティを見て自動的に値を詰めてくれます。

この仕組みを利用することで、入力フォームの値をJavaのオブジェクトとして扱えるため、バリデーションやデータベースへの保存などの処理が簡単になります。

つまり、@ModelAttributeは、フォームのデータとJavaコードを結ぶ接着剤のような存在であり、Spring MVCにおける非常に基本的かつ重要な役割を持っているのです。

また、@ModelAttributeを使うことで、画面からのリクエストパラメータを明確に扱うことができるため、保守性の高いコードを書くことができます。

3. @ModelAttributeを使った具体的なコントローラの書き方

ここでは、@ModelAttributeを使ってフォームの値を受け取る具体的な方法について解説します。Spring MVCでは、@Controllerクラスに定義したメソッドで@ModelAttributeを使うことで、フォームから送られた値をFormクラスのインスタンスとして受け取ることができます。

以下のようなコントローラクラスを作成します。


@Controller
public class UserController {

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

    @PostMapping("/user")
    public String submitForm(@ModelAttribute UserForm userForm, Model model) {
        model.addAttribute("name", userForm.getName());
        model.addAttribute("email", userForm.getEmail());
        return "userResult";
    }
}

showFormメソッドでは、フォームの初期表示のために空のUserFormオブジェクトを生成してビューに渡します。submitFormメソッドでは、@ModelAttributeによってHTMLフォームから送信された値が自動的にUserFormにバインディングされます。

これにより、複雑なリクエスト処理を手動で行わずに済み、可読性とメンテナンス性の高いコードを書くことができます。

4. HTMLフォームとの連携とname属性の重要性

HTMLフォームとFormクラスのプロパティを正しく連携させるためには、HTMLのname属性が非常に重要です。Spring MVCは、name属性とFormクラスのプロパティ名が一致しているかどうかを見て、値を正しくバインディングします。

以下のようなHTMLフォームの記述があるとします。


<form action="/user" method="post">
    <label for="name">名前:</label>
    <input type="text" id="name" name="name" /><br>

    <label for="email">メールアドレス:</label>
    <input type="email" id="email" name="email" /><br>

    <input type="submit" value="送信" />
</form>

この例では、name="name"とname="email"が指定されています。これらの値は、JavaのFormクラスに定義されているnameフィールドおよびemailフィールドと一致していなければなりません。

もしHTML側のname属性がuserNameなど異なる名前になっている場合、Springは正しく値をバインディングできません。一致していることがバインディングの大前提です。

このため、HTMLを作成する際は、name属性の名前をFormクラスのプロパティと完全に一致させることが基本ルールとなります。

5. Formクラスの定義と役割を理解しよう

Formクラスは、HTMLフォームとSpring MVCのコントローラの間でデータを受け渡すためのJavaクラスです。このクラスは特別な親クラスを継承する必要はなく、通常のJavaクラス（POJO）として定義できます。

主な役割は、フォームの入力項目に対応するフィールド（変数）を持ち、バインディングの受け皿として機能することです。また、JavaBeansの規約に従って、getterとsetterを正しく定義することが求められます。

以下は、UserFormという名前のFormクラスの一例です。


public class UserForm {
    private String name;
    private String email;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

このUserFormクラスには、nameとemailという2つのフィールドがあります。これらは、それぞれHTMLフォームのname="name"とname="email"に対応しています。

また、Spring MVCでは、フィールドへの直接アクセスではなく、getterとsetterを通じて値を操作するため、必ずgetXxxとsetXxxのメソッドを定義しておきましょう。

このように、Formクラスは、HTMLフォームのデータを受け取るための箱であり、コントローラとのやり取りを効率よくするために欠かせない構成要素です。

また、バリデーションやエラーメッセージの表示など、次のステップで扱う処理にも密接に関係してくるため、Formクラスの設計はとても重要です。

6. @ModelAttributeと@Valid、BindingResultによるバリデーション処理

Spring MVCでは、フォームから送信されたデータを受け取る際に、同時にバリデーション（入力値の検証）を行うことができます。これを実現するために使うのが@ValidとBindingResultです。

@ModelAttributeでフォームの値を受け取るメソッドに@Validを追加すると、自動的にバリデーションが実行されます。そして、バリデーションエラーがあったかどうかの結果は、BindingResultという引数に格納されます。

以下は、@ValidとBindingResultを使った具体例です。


@PostMapping("/user")
public String submitForm(@Valid @ModelAttribute UserForm userForm, BindingResult result, Model model) {
    if (result.hasErrors()) {
        return "userForm";
    }
    model.addAttribute("name", userForm.getName());
    model.addAttribute("email", userForm.getEmail());
    return "userResult";
}

バリデーション対象のクラス（ここではUserForm）には、入力値をチェックするアノテーションを付けます。たとえば、次のように記述します。


import jakarta.validation.constraints.*;

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

    @NotBlank(message = "メールアドレスを入力してください。")
    @Email(message = "正しいメールアドレスの形式で入力してください。")
    private String email;

    // getterとsetterは省略
}

@NotBlankは「空文字ではいけない」、@Emailは「メールアドレス形式でなければならない」というバリデーションルールを指定しています。

このように、@ValidとBindingResultを組み合わせることで、フォームの入力値を安全にチェックしながら受け取ることができます。

7. エラーメッセージの表示方法（Thymeleafを使った例）

フォームに入力された値にバリデーションエラーがあった場合、エラーメッセージをユーザーに表示することが重要です。Spring MVCとThymeleafを使えば、BindingResultに含まれるエラー情報を簡単に画面に出力することができます。

以下は、Thymeleafを使ったフォームの例です。


<form action="/user" method="post" th:object="${userForm}">
    <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="email">メールアドレス:</label>
        <input type="email" id="email" th:field="*{email}" />
        <div th:if="${#fields.hasErrors('email')}" th:errors="*{email}"></div>
    </div>

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

th:fieldは、フォームとFormクラスのプロパティを結びつけるためのThymeleafの属性です。th:errorsは、該当するフィールドにバリデーションエラーがある場合に、そのメッセージを表示します。

この仕組みを使うことで、どの項目にどんなエラーがあるのかをユーザーにわかりやすく伝えることができるようになります。

画面から送信されたデータに対して、即座にエラーメッセージを返すことで、ユーザー体験も大幅に向上します。

8. よくあるエラーとその対処法

Spring MVCで@ModelAttributeを使ってフォームの値を受け取る際、初心者がつまずきやすいエラーがあります。ここでは、よくあるエラーとその対処法をまとめます。

name属性とプロパティ名が一致していない

HTMLのname属性とFormクラスのプロパティ名が一致していないと、バインディングが行われません。

たとえば、HTMLがname="username"なのに、Formクラスがprivate String name;のようになっていると、値が渡りません。

対応策： name属性の値は、Formクラスのフィールド名と一致させる。

getterやsetterの記述漏れ

Formクラスのフィールドにgetterやsetterが定義されていないと、Springは値を読み書きできません。

対応策： すべてのプロパティにpublicなgetterとsetterを定義する。

BindingResultの位置が間違っている

バリデーション処理でBindingResultを使う場合、必ず@Validの引数の直後に書く必要があります。


// 正しい例
public String submitForm(@Valid @ModelAttribute UserForm form, BindingResult result)

// 間違った例（BindingResultの順番が不正）
public String submitForm(BindingResult result, @Valid @ModelAttribute UserForm form)

対応策： @Validの直後にBindingResultを記述すること。

入力値がnullでNullPointerExceptionが発生

バリデーションを使っていない場合や、初期値の設定を忘れていると、nullの値にアクセスしてNullPointerExceptionが発生することがあります。

対応策： @NotBlankなどのバリデーションアノテーションを適切に使う。また、Formクラスのフィールドにデフォルト値を持たせることも検討する。

これらのエラーは、Spring MVCの仕組みや@ModelAttributeの動作を理解することで未然に防ぐことが可能です。最初は難しく感じるかもしれませんが、パターンを覚えれば自然に対応できるようになります。

まとめ

本記事では、Spring MVCにおける@ModelAttributeの役割や、HTMLフォームとの連携、Formクラスの設計方法、@ValidとBindingResultによるバリデーション処理、Thymeleafを使ったエラーメッセージ表示など、フォーム送信処理で必ず理解すべき基礎を体系的に学びました。とくに初心者が最初につまずきやすいポイントとして、name属性とフォームクラスのプロパティ名が一致していない問題、getter・setterの不足、BindingResultの順番ミスなどがあり、これらはすべてSpring MVCがフォームデータを自動バインディングする仕組みを正しく理解することで未然に防ぐことができます。また、@ModelAttributeを使う大きなメリットは、HTMLから送られてきたリクエストパラメータをJavaのFormクラスに自動で詰めてくれる点です。これにより、開発者は複雑な処理を記述する必要がなく、可読性の高いコードを維持できます。さらに、Spring MVCとThymeleafを組み合わせて使うことで、フォーム入力欄との連携、エラー表示、バリデーション処理を画面側で直感的に表現できるため、初心者でも学習しやすい環境が整っています。 SEOの観点では、「Spring MVC フォーム送信」「@ModelAttribute 使い方」「Formクラスバリデーション」「BindingResult エラー」「Thymeleaf フォームバインディング」などの検索語句を自然に盛り込みつつ、学習者がよく検索する「初心者向け Spring Boot フォーム処理」「入力フォームの受け取り方」「Java Web フォーム連携」「@Valid の基本」などの重要キーワードも多く含めています。さらに、初心者が理解しやすい構造を保ちながら、フォーム送信からコントローラ処理、バリデーション、結果画面表示までの一連の流れを俯瞰できる内容にすることで、学習効果が非常に高いまとめとなっています。以下に、実際に記事で学んだ内容を反映したサンプルコードをまとめとして掲載します。構文の理解と全体の流れを振り返る参考にしてください。

@ModelAttributeを使ったサンプルプログラム


@Controller
public class UserController {

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

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

        if (result.hasErrors()) {
            return "userForm";
        }

        model.addAttribute("name", userForm.getName());
        model.addAttribute("email", userForm.getEmail());
        return "userResult";
    }
}


public class UserForm {

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

    @NotBlank(message = "メールアドレスを入力してください。")
    @Email(message = "正しい形式で入力してください。")
    private String email;

    public String getName() { return name; }

    public void setName(String name) { this.name = name; }

    public String getEmail() { return email; }

    public void setEmail(String email) { this.email = email; }
}

新卒エンジニアと先輩社員の振り返り会話

新人：「@ModelAttributeってどこで何をしているのか分からなかったのですが、フォームのname属性とJavaのプロパティをつないでいる重要な役割なんですね！」

先輩：「そのとおり。Spring MVCの肝となる仕組みだから、ここを理解すると一気に開発が楽になるよ。」

新人：「バリデーションの@ValidとBindingResultの順番も、理由が分かると覚えやすいです。間違えるとエラーになりやすいところですよね。」

先輩：「フォーム系の処理はミスしやすいけど、@ModelAttribute・Formクラス・バリデーションの流れをセットで覚えておけば安心だよ。」

新人：「Thymeleafのth:fieldやth:errorsも便利ですね。画面側でエラー内容が簡単に表示できるのがすごいです！」

先輩：「Spring MVCとThymeleafは相性がいいからね。今回学んだ流れは必ず実務で役立つよ。」