SpringでPOSTメソッドを使ってデータ登録！初心者向けHTTPリクエスト解説

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

新人

「Webアプリケーションでフォームの内容を送信して、サーバーにデータ登録したいんですけど、どうすればいいですか？」

先輩

「それなら、HTTPのPOSTメソッドを使うのが基本だよ。Springでもよく使うから覚えておこう。」

新人

「GETとはどう違うんですか？」

先輩

「そこも大事なポイントだね。じゃあ、POSTメソッドの基本から説明するよ！」

1. POSTメソッドとは？

POSTメソッドとは、HTTPのリクエストメソッドのひとつで、ブラウザからサーバーへデータを送信して登録処理を行うために使います。たとえば、ユーザー登録フォームや商品追加など、「何かを新しく作る・追加する」処理に最適です。

HTTPの基本では、次のようなリクエスト形式になります。


POST /register HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 29

username=springuser&age=25

このように、リクエストの本文（Body）に登録する情報を含めて、サーバーに送信するのが特徴です。

2. GETとPOSTの違いをやさしく解説

HTTPにはいくつかのメソッドがありますが、よく使われるのがGETメソッドとPOSTメソッドです。

GETメソッドは、主にデータの取得に使われます。一方で、POSTメソッドはデータの登録・更新といった「サーバー側で状態が変わる」処理に使います。

たとえば、GETメソッドでは次のようにURLにパラメータを付けて送信します。


GET /search?keyword=spring HTTP/1.1
Host: example.com

一方、POSTメソッドでは次のようにリクエストボディにデータを含めて送信します。


POST /submit HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

title=SpringGuide&content=LearnSpring

セキュリティ面でもPOSTメソッドのほうが安全です。なぜなら、URLにデータが表示されず、パスワードなどの機密情報を扱うときに適しているからです。

3. SpringでPOSTメソッドを使う準備

それでは、実際にSpringフレームワークでPOSTメソッドを使ってデータ登録を行う方法を見ていきましょう。ここでは、Gradleを使った開発環境（pleiades）を前提に進めます。

まずはSpring BootのプロジェクトをGradleで作成しましょう。依存関係はpleiadesのSpring Bootスターター（spring-boot-starter-web）をチェックすることで簡単に追加できます。


@Controller
public class UserController {

    @PostMapping("/register")
    @ResponseBody
    public String register(@RequestParam String username, @RequestParam int age) {
        // サーバー側でデータを受け取り処理
        return "ユーザー「" + username + "」を登録しました（年齢：" + age + "）";
    }
}

この@Controllerクラスは、Springの中でPOSTメソッドを使ってデータ登録を受け取る部分です。ポイントは、次の3つです。

@PostMappingでPOSTリクエストのパスを指定
@RequestParamでブラウザから送られたデータを受け取る
@ResponseBodyで戻り値をそのままブラウザに表示

フォーム側のHTMLは以下のようになります。


<form method="post" action="/register">
    <label>ユーザー名：<input type="text" name="username"></label><br>
    <label>年齢：<input type="number" name="age"></label><br>
    <button type="submit">登録する</button>
</form>

このフォームから「ユーザー名」と「年齢」をPOSTメソッドで送信すると、Springのコントローラが受け取り、サーバー側で登録処理を実行します。

ブラウザからフォームを送信すると、次のようなレスポンスが返ってきます。


ユーザー「springuser」を登録しました（年齢：25）

このように、Springではとても簡単にHTTPのPOSTメソッドを使ったデータ登録ができます。サーバー側での受け取り・処理・応答の一連の流れがわかりやすく整理されているのがSpringの強みです。

4. フォームからのPOST送信を受け取る方法（@RequestParamを使う例）

フォームから送られたデータは、Springの@RequestParamアノテーションを使って受け取ることができます。HTMLフォームとサーバーのJavaコードがうまく連携することがポイントです。

フォームでは、inputタグのname属性が重要で、サーバー側で受け取る変数名と一致させる必要があります。


<form method="post" action="/contact">
    <label>お名前：<input type="text" name="name"></label><br>
    <label>メールアドレス：<input type="email" name="email"></label><br>
    <label>メッセージ：<textarea name="message"></textarea></label><br>
    <button type="submit">送信</button>
</form>

このフォームから送られたデータをSpringの@Controllerで受け取るには、以下のように記述します。


@Controller
public class ContactController {

    @PostMapping("/contact")
    @ResponseBody
    public String receiveForm(
            @RequestParam String name,
            @RequestParam String email,
            @RequestParam String message) {

        return "お問い合わせありがとうございます。" + name + "さん（" + email + "）のメッセージ：" + message;
    }
}

@RequestParamは、HTTPリクエストのパラメータを個別に受け取るためのアノテーションです。フォームのname属性と一致させることで、値が自動的にバインドされます。

この方法は、フォームからの入力項目が固定で、数も少ない場合に使いやすく、SpringのPOSTメソッド処理では基本的なスタイルです。

5. JSONで送られたデータを受け取る方法（@RequestBodyは使わない）

フォーム以外にも、JavaScriptなどからHTTPのPOSTメソッドでJSON形式のデータを送信することがあります。

たとえば、以下のようにJavaScriptからJSONを送信する場合です。


fetch("/api/send", {
    method: "POST",
    headers: {
        "Content-Type": "application/json"
    },
    body: JSON.stringify({
        username: "springuser",
        comment: "こんにちは！"
    })
});

Spring側では、通常@RequestBodyでJSONデータを受け取る方法がありますが、この記事では@RequestBodyを使わずに、別の形で処理する方法を紹介します。

その方法とは、ServletRequestオブジェクトを使ってリクエストの生データを受け取るスタイルです。


@Controller
public class JsonReceiveController {

    @PostMapping("/api/send")
    @ResponseBody
    public String receiveJson(HttpServletRequest request) throws IOException {
        StringBuilder sb = new StringBuilder();
        BufferedReader reader = request.getReader();
        String line;

        while ((line = reader.readLine()) != null) {
            sb.append(line);
        }

        String receivedJson = sb.toString();
        return "受け取ったJSONデータ：" + receivedJson;
    }
}

この例では、HTTPのリクエストボディを直接読み取ることで、POSTメソッドで送られたJSON形式のデータを文字列として受け取ります。

データの形式や構造を自由に扱える一方で、文字列のまま処理するため、パースやバリデーションは自前で行う必要があります。

小規模なAPIや、単純なデバッグ用途で使うのに向いています。

6. レスポンスとして文字列やMapを返す例（@ResponseBodyで）

POSTメソッドでデータ送信を受け取った後は、クライアント（ブラウザやJavaScript）に対して何らかのレスポンスを返す必要があります。

Springでは、@ResponseBodyアノテーションを付けることで、戻り値を直接HTTPレスポンスとして返すことができます。

たとえば、文字列を返す場合の例です。


@Controller
public class SimpleResponseController {

    @PostMapping("/reply")
    @ResponseBody
    public String replyMessage(@RequestParam String name) {
        return name + "さん、こんにちは！メッセージを受け付けました。";
    }
}

この例では、nameパラメータを受け取り、それを使ってレスポンスの文字列を組み立てています。

また、JSON形式のレスポンスを返したい場合には、Mapを使う方法もあります。


@Controller
public class JsonResponseController {

    @PostMapping("/jsonreply")
    @ResponseBody
    public Map<String, Object> jsonReply(@RequestParam String item, @RequestParam int count) {
        Map<String, Object> response = new HashMap<>();
        response.put("item", item);
        response.put("count", count);
        response.put("status", "受け取り完了");

        return response;
    }
}

このように、Mapを返すと、自動的にJSON形式に変換されてブラウザに返されます。Springでは、これを「自動シリアライズ」と呼びます。

フォームからのデータ送信でも、JavaScriptによるPOSTメソッドでも、サーバーからのレスポンスの形を工夫することで、クライアント側の処理を柔軟に制御することができます。

7. ブラウザやcurlでPOSTを送信して確認する方法

POSTメソッドを使ったリクエストは、HTMLフォームからだけでなく、コマンドラインツールのcurlを使っても簡単にテストできます。Springで作ったAPIやコントローラが正しく動作するかを確認する際に便利です。

たとえば、下記のようなcurlコマンドでPOSTメソッドを送信できます。


curl -X POST http://localhost:8080/register \
-d "username=testuser&age=20" \
-H "Content-Type: application/x-www-form-urlencoded"

このコマンドでは、-X POSTでPOSTメソッドを指定し、-dで送信するデータを設定します。-HでHTTPヘッダー（ここではContent-Type）を指定しています。

ブラウザからは、前の章で紹介したようにformタグで送信ボタンを押すことで、POSTリクエストが発生します。

POSTメソッドの動作確認をする際には、curlを使って素早く検証し、ブラウザでは実際のフォーム画面でユーザー操作を試す、という使い分けが効果的です。

8. よくあるエラーと対処法（415、400、405など）

POSTメソッドを使ったリクエストでSpringアプリケーションを開発していると、HTTPステータスコードによるエラーに遭遇することがあります。ここでは代表的なエラーとその対処法を紹介します。

① 415 Unsupported Media Type

このエラーは、リクエストのContent-Typeがサーバー側で受け入れられていない場合に発生します。


HTTP Status 415 – Unsupported Media Type

たとえば、Content-Type: application/jsonで送ったのに、Spring側が文字列しか受け取れない構成になっているときに出ます。対策としては、Content-Typeの値をapplication/x-www-form-urlencodedに変更するか、受け取り側をJSONに対応させる必要があります。

② 400 Bad Request

リクエストの形式が不正なときに返されるエラーです。


HTTP Status 400 – Bad Request

このエラーは、必要なパラメータが不足していたり、数値を文字列として送信していた場合などに発生します。たとえば、コントローラで@RequestParam int ageと定義されているのに、非数値の値（"abc"など）を送ると400エラーになります。

③ 405 Method Not Allowed

指定されたURLが、許可されていないHTTPメソッドでアクセスされた場合に出ます。


HTTP Status 405 – Method Not Allowed

たとえば、@PostMapping("/submit")としているメソッドに対して、ブラウザからGETリクエストでアクセスした場合などです。指定したURLとHTTPメソッドが一致しているかをよく確認しましょう。

9. よくある初心者のつまずき（URL間違い、パラメータ不足、メソッド不一致など）

SpringでPOSTメソッドを使ってデータ送信を扱う際、初心者がよくつまずくポイントがあります。ここでは代表的なミスを紹介し、事前に防げるように解説します。

① URLの指定ミス

フォームのaction属性やcurlの送信先URLが間違っていると、リクエストが正しく届かず、404 Not Foundエラーになります。コントローラで定義した@PostMapping("/register")のようなURLと、送信先のURLが一致しているか確認しましょう。

② パラメータ名の不一致

フォームのinput nameと、@RequestParamで受け取る変数名が異なると、値がバインドされず、エラーになります。


// NG：フォームのname="username"なのに、受け取る側が違う名前
@PostMapping("/register")
@ResponseBody
public String register(@RequestParam String user) {
    return "登録：" + user;
}

このように名前がずれていると、Required request parameter 'user' is not presentというエラーが出ます。

③ メソッドの不一致

ブラウザやcurlでPOSTリクエストを送っているつもりでも、実際にはGETになっていることがあります。特に、formタグでmethod="post"を指定し忘れると、自動的にGETメソッドになります。


<!-- NG：method属性がないため、デフォルトでGETになる -->
<form action="/register">
    <input type="text" name="username">
    <button type="submit">送信</button>
</form>

必ずmethod="post"を明示的に指定しましょう。

④ サーバーが起動していない

意外と見落としやすいのが、Springアプリケーション自体が起動していないというケースです。pleiadesからGradle経由でSpring Bootアプリを実行しておく必要があります。

上記のようなトラブルは、どれも経験することで慣れていきますが、HTTPステータスコードとエラーメッセージの内容をよく読むことで、原因がすぐに見つかることも多いです。