@PostMappingを使ってフォームを受け取る流れを初心者向けに解説！

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

新人

「Spring Bootで画面に入力フォームを作って、そこに入力されたデータをサーバーで受け取りたいんですが、どうすればいいですか？」

先輩

「その場合は、@PostMappingというアノテーションを使うのが基本です。フォームに入力された値を、Springのコントローラーで受け取れるようになりますよ。」

新人

「@PostMappingって、どんなことができるんですか？Javaのメソッドに付けるだけで良いんですか？」

先輩

「そうですね、実際に使い方を見ながら、フォームの送信と連携する仕組みを丁寧に解説していきます！」

1. @PostMappingとは？

Spring Bootにおける@PostMappingは、HTMLフォームなどから送信されるデータをPOSTリクエストとして受け取るためのアノテーションです。Javaのクラスの中で、特定のメソッドに対して@PostMappingを付けることで、フォームから送られたデータを受け取る機能を実装できます。

Spring Frameworkでは、Web画面とサーバー側の連携をシンプルに行うために、こういったアノテーション（特別な命令）を使います。特にフォームとの連携では、@PostMappingがとても重要な役割を果たします。

2. @PostMappingを使うと何ができるのか

@PostMappingを使うことで、次のようなフォーム処理が可能になります。

入力フォームに書かれたデータをJavaのクラスに取り込む
ユーザーが送信した内容を確認したり、データベースに保存したりできる
他の画面に結果を表示するなどのレスポンス処理が可能になる

たとえば、以下のようにコントローラクラスに@PostMappingを使ったメソッドを書くことで、HTMLのフォームと接続できます。


@Controller
public class ContactController {

    @PostMapping("/submit")
    public String submitForm(String name, String email) {
        System.out.println("名前：" + name);
        System.out.println("メール：" + email);
        return "result";
    }
}

このように、@PostMappingはフォームデータを受け取る「入り口」として働きます。

3. フォームから値を送る仕組み

フォームを使ってユーザーからの入力を受け取るには、HTMLフォームを使ってデータをサーバーに送信する必要があります。フォームは「どこに送るか」「どの方法で送るか」を指定できます。

たとえば、以下のようにHTMLファイル内で<form>タグを使って記述します。


<form action="/submit" method="post">
    <label>名前：</label>
    <input type="text" name="name"><br>
    <label>メール：</label>
    <input type="email" name="email"><br>
    <button type="submit">送信</button>
</form>

このフォームでは、入力された「名前」と「メール」が、actionで指定されたURL（ここでは/submit）に対してPOSTメソッドで送信されます。

Spring側では、先ほど紹介した@PostMapping("/submit")の部分で、HTMLフォームからのリクエストを受け取ることができます。

このように、HTMLとSpringの連携によって、画面からサーバーへ安全にデータを渡すことができるのです。

4. コントローラクラスの作成と@PostMappingの書き方

Spring BootでHTMLフォームの入力を受け取るには、@Controllerアノテーションを付けたクラスを作成し、そこに@PostMappingを記述したメソッドを用意します。

まず、pleiadesで作成したプロジェクトのsrc/main/javaディレクトリ内に、controllerパッケージを作ってクラスを定義します。


package com.example.demo.controller;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;

@Controller
public class ContactController {

    @PostMapping("/submit")
    public String handleForm(
            @RequestParam("name") String name,
            @RequestParam("email") String email) {

        System.out.println("受け取った名前：" + name);
        System.out.println("受け取ったメール：" + email);
        return "result";
    }
}

@Controllerを付けることで、このクラスがWebリクエストを受け取る役割であるとSpringが認識します。

また、@RequestParamを使うことで、フォームの中のname属性の値をJavaの変数として受け取ることができます。ここでは、「name」と「email」がそれぞれの引数に入ります。

5. HTMLフォームを作って画面に表示する方法（Thymeleaf使用）

フォーム画面は、src/main/resources/templatesディレクトリにHTMLファイルを作成し、Thymeleafテンプレートエンジンを使って記述します。ファイル名はform.htmlなど分かりやすい名前にします。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>お問い合わせフォーム</title>
</head>
<body>
    <h2>お問い合わせフォーム</h2>
    <form th:action="@{/submit}" method="post">
        <label>名前：</label>
        <input type="text" name="name"><br><br>
        <label>メール：</label>
        <input type="email" name="email"><br><br>
        <button type="submit">送信</button>
    </form>
</body>
</html>

ここでは、th:action="@{/submit}"とすることで、Spring側の@PostMapping("/submit")と正しく接続されます。

このHTMLを表示するためには、@GetMappingで対応する画面表示の処理も必要になります。コントローラクラスに以下を追加しましょう。


@GetMapping("/form")
public String showForm() {
    return "form";
}

これで、/formにアクセスするとform.htmlが表示され、入力フォームからPOSTリクエストが送れるようになります。

6. HTMLフォームからPOSTでデータを送信する流れ

ここまでで、HTML画面を表示して、そこから@PostMappingにPOSTリクエストを送る基本の流れができました。全体の流れを整理すると、以下のようになります。

ユーザーがブラウザで/formにアクセス
Springがform.htmlを表示
フォームに名前とメールを入力し、「送信」ボタンを押す
フォームの内容が/submitにPOST送信される
@PostMapping("/submit")がそのデータを受け取る
Javaのメソッド内でデータを処理し、画面遷移（または確認画面表示）

このように、Spring Boot フォーム処理では、@GetMappingと@PostMappingを組み合わせて、入力画面と送信先の処理をしっかり分けて実装するのが基本です。

今回は@RequestParamで単純なデータを受け取りましたが、次回は@ModelAttributeや専用のFormクラスを使って、より複雑なデータを安全に扱う方法も紹介できます。

また、Spring Bootの開発環境としては、pleiadesでGradleを使って構成するのが一般的です。依存関係はSpring WebとThymeleafを含めれば、ここまでのフォーム処理が可能になります。

7. コントローラで受け取ったデータの確認方法（@ModelAttributeとFormオブジェクト）

ここからは、@ModelAttributeを使ってフォームの値を1つのオブジェクトとして受け取る方法を解説します。これにより、複数の入力項目をまとめて扱えるようになります。

まずは、フォームデータを格納するためのJavaクラス（Formオブジェクト）を作成します。例えば、ContactFormという名前のクラスを作成します。


package com.example.demo.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;
    }
}

次に、コントローラでこのFormクラスを使って値を受け取るようにします。ポイントは、@ModelAttributeをメソッド引数に付けることです。


package com.example.demo.controller;

import com.example.demo.form.ContactForm;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.PostMapping;

@Controller
public class ContactController {

    @PostMapping("/submit")
    public String handleSubmit(@ModelAttribute ContactForm form) {
        System.out.println("名前：" + form.getName());
        System.out.println("メール：" + form.getEmail());
        return "result";
    }
}

このように@ModelAttributeを使えば、複数のフォーム項目を1つのJavaオブジェクトとしてまとめて受け取ることができます。

8. フォームから送信された値の画面表示

フォームで送信されたデータを、送信後の画面（確認画面や完了画面など）に表示するには、Thymeleafを使ってテンプレートに値を渡します。

先ほどのhandleSubmitメソッドを、値を画面に表示できるように修正します。


import org.springframework.ui.Model;

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

このコードでは、SpringのModelを使って画面に渡すデータを登録しています。次に、result.htmlを作成して、画面に送信内容を表示しましょう。


<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>送信結果</title>
</head>
<body>
    <h2>送信ありがとうございました！</h2>
    <p>以下の内容を受け取りました。</p>
    <ul>
        <li>名前：<span th:text="${name}"></span></li>
        <li>メール：<span th:text="${email}"></span></li>
    </ul>
</body>
</html>

このようにすれば、フォームで入力された値を確認画面として表示することができます。

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

Spring Bootで@PostMappingを使ってフォーム処理をする際、初心者がよくつまずくポイントとその解決方法を紹介します。

① HTTP 405 エラー（Method Not Allowed）

このエラーは、HTMLフォームがPOSTで送信されているのに、Spring側で@PostMappingではなく@GetMappingで受け取ろうとしている場合に発生します。

→ 対処法：フォームのmethod="post"に対して、Springのコントローラでは@PostMappingを使ってください。

② リクエストのURLが一致しない

フォームのaction属性に設定したパスと、コントローラの@PostMappingで指定したパスが一致していないと、リクエストが正しく届きません。

→ 対処法：HTMLではth:action="@{/submit}"、Javaでは@PostMapping("/submit")を揃えましょう。

③ フォームデータが受け取れない

フォームのname属性と、Javaの受け取り変数名が一致していない場合、データが受け取れません。

→ 対処法：@RequestParamや@ModelAttributeを使うときは、フォームのnameと一致させてください。

④ result.htmlが表示されない

テンプレート名が間違っているか、templatesフォルダの配置場所が正しくない可能性があります。

→ 対処法：HTMLファイルは必ずsrc/main/resources/templatesに置いて、拡張子は.htmlにしましょう。

これらはSpringフォーム処理でよくあるつまずきです。原因を1つずつ見直せば、必ず解決できます。