JavaのSpringで@PutMappingアノテーションを使ったHTTP PUTリクエストの使い方

Springの@PutMappingアノテーション

先生と生徒の会話形式で理解しよう

生徒

「JavaのSpringでデータを更新したいんですが、どうしたらいいですか？」

先生

「データを更新するなら、@PutMappingアノテーションが役立ちますよ。HTTP PUTリクエストを使ってデータを更新できます。」

生徒

「その使い方を教えてください！」

先生

「では、実際のコードを使って見ていきましょう。」

1. @PutMappingアノテーションとは？

@PutMappingアノテーションは、SpringフレームワークでHTTP PUTリクエストを処理するために使われます。このアノテーションを使うことで、既存のデータを更新するためのエンドポイントを簡単に作成できます。例えば、ユーザーの情報を更新する際に使用されます。

2. @PutMappingアノテーションを使った基本的な実装

まず、@PutMappingアノテーションを使った基本的な実装例を紹介します。以下のコードは、ユーザーの情報を更新するコントローラの例です。


import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PutMapping("/update-user")
    public String updateUser(@RequestParam("id") Long id, @RequestBody User user) {
        // ここでユーザー情報を更新するロジックを追加
        return "ユーザーID " + id + " の情報が更新されました";
    }
}

この例では、@PutMapping("/update-user")がエンドポイントを設定し、HTTP PUTリクエストに応答するようになっています。@RequestParamでユーザーIDを取得し、@RequestBodyで更新する情報を受け取ります。

3. @RequestBodyを使ったデータの受け渡し

@PutMappingと共に使う@RequestBodyアノテーションは、クライアントから送られてきたJSON形式のデータをJavaオブジェクトとして受け取るために使用されます。以下のUserクラスの例にあるフィールドは、ユーザーの名前やメールアドレスなどの情報を保持します。


public class User {
    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;
    }
}

このUserクラスを利用して、ユーザーの情報をJSONとして送信し、@RequestBodyで受け取って処理することができます。

4. PUTリクエストの実行例

次に、HTTP PUTリクエストを実行して、ユーザー情報を更新する手順を示します。以下は、curlコマンドを使ったリクエストの例です。


curl -X PUT -H "Content-Type: application/json" -d '{"name": "山田太郎", "email": "yamada@example.com"}' "http://localhost:8080/update-user?id=1"

このコマンドを実行すると、IDが1のユーザーのnameとemailが更新されます。PUTリクエストにより、サーバー側でデータが更新されます。

5. JSONデータの受け取りとエラーハンドリング

PUTリクエストで送られるJSONデータは、Javaオブジェクトに自動的に変換されます。しかし、データの形式が不正な場合や必須フィールドが欠けている場合は、エラーが発生することがあります。以下のように、例外をキャッチしてエラーハンドリングを追加できます。


import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;

@RestController
public class UserController {

    @PutMapping("/update-user")
    public String updateUser(@RequestParam("id") Long id, @RequestBody User user) {
        if (user.getName() == null || user.getEmail() == null) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "名前とメールアドレスは必須です");
        }
        return "ユーザーID " + id + " の情報が更新されました";
    }

    @ExceptionHandler(ResponseStatusException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String handleException(ResponseStatusException e) {
        return e.getReason();
    }
}

このコードでは、ResponseStatusExceptionを使用して、必要なデータが欠けている場合にエラーを返しています。これにより、データの整合性を保ち、ユーザーに有益なエラーメッセージを提供できます。

6. @PathVariableを使ったURL設計

先ほどの例では、クエリパラメータ（?id=1のような形式）を使ってユーザーIDを渡していましたが、REST APIではURLパスの一部としてIDを渡す書き方もよく使われます。その際に役立つのが@PathVariableアノテーションです。

以下のコードは、ユーザーIDをURLに含めて受け取るパターンの例です。


import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PutMapping("/users/{id}")
    public String updateUser(@PathVariable("id") Long id, @RequestBody User user) {
        // ここでIDに対応するユーザー情報を更新するロジックを追加
        return "ユーザーID " + id + " の情報が更新されました（@PathVariable版）";
    }
}

@PathVariable("id")を使うことで、/users/1のようなURLパスから値を取得できます。クエリパラメータを使うか、パス変数を使うかは設計方針によりますが、RESTfulなAPIではパス変数を使うケースが多く見られます。

7. サービスクラスと組み合わせた実践的な更新処理

実際のアプリケーションでは、コントローラクラスの中に更新ロジックをすべて書くのではなく、サービスクラスに処理を分離するのが一般的です。こうすることで、コードの見通しが良くなり、テストもしやすくなります。

以下は、サービスクラスを使ってユーザー情報を更新する例です。


import org.springframework.stereotype.Service;

@Service
public class UserService {

    public void updateUser(Long id, User user) {
        // 本来はリポジトリを呼び出してDBを更新する処理を書く
        // ここでは説明用に簡略化
        System.out.println("ID " + id + " のユーザーを更新しました: "
                + user.getName() + ", " + user.getEmail());
    }
}


import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @Autowired
    private UserService userService;

    @PutMapping("/users/{id}")
    public String updateUser(@PathVariable("id") Long id, @RequestBody User user) {
        userService.updateUser(id, user);
        return "ユーザーID " + id + " の情報が更新されました（サービスクラス使用）";
    }
}

このように、@PutMappingで受け取ったリクエストデータをサービスクラスに渡して処理させることで、役割分担がはっきりし、保守性の高いSpringアプリケーションを構築できます。

8. PUTとPOSTの違いと使い分け

@PutMappingとよく比較されるのが、@PostMappingを使ったHTTP POSTリクエストです。どちらもデータを送信するために使いますが、意味合いや使いどころが異なります。

一般的には、次のように使い分けます。

POST：新規作成（新しいリソースを追加）するときに使う
PUT：既存データの置き換え・更新を行うときに使う

例えば、新しいユーザーを登録する場合は@PostMapping("/users")を使い、既存ユーザーを更新する場合は@PutMapping("/users/{id}")を使う、という設計がよく見られます。


@RestController
public class UserController {

    // 新規作成（POST）
    @PostMapping("/users")
    public String createUser(@RequestBody User user) {
        // ユーザーを新規登録する処理
        return "ユーザー " + user.getName() + " を作成しました";
    }

    // 更新（PUT）
    @PutMapping("/users/{id}")
    public String updateUser(@PathVariable("id") Long id, @RequestBody User user) {
        // 既存ユーザーを更新する処理
        return "ユーザーID " + id + " の情報が更新されました";
    }
}

このように、HTTPメソッドごとの役割を意識して@PutMappingと@PostMappingを使い分けることで、APIの設計意図がわかりやすくなり、利用する側にとっても理解しやすいREST APIになります。

まとめ

ここまで、JavaのSpringフレームワークでの@PutMappingアノテーションの使い方について学んできました。@PutMappingを使うことで、エンドポイントの作成と、HTTP PUTリクエストを介してのデータの更新が効率的に実装できることが理解できたと思います。@RequestParamでのID指定、@RequestBodyでのデータ受け取り、エラーハンドリングの重要性も把握しました。

Spring BootでのAPI設計は、シンプルで一貫性があり、特にデータの更新とエラーハンドリングにおいて高い柔軟性を発揮します。今回の学びを通じて、curlコマンドを使ったPUTリクエストの送信方法や、クライアント側から送信されたJSONデータの受け取りと処理も確認しました。

まとめると、@PutMappingは、既存データの更新に特化したエンドポイントを実装するための便利なツールです。クライアントサイドからデータを効率よく受け取り、必要な処理を行うことで、Springアプリケーションがデータの整合性を保ちながら適切に動作するようになります。


@RestController
public class UserController {

    @PutMapping("/update-user")
    public String updateUser(@RequestParam("id") Long id, @RequestBody User user) {
        if (user.getName() == null || user.getEmail() == null) {
            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "名前とメールアドレスは必須です");
        }
        return "ユーザーID " + id + " の情報が更新されました";
    }

    @ExceptionHandler(ResponseStatusException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public String handleException(ResponseStatusException e) {
        return e.getReason();
    }
}

このように、ユーザー情報の更新エンドポイントを作成することができ、エラーハンドリングを通じてクライアント側にわかりやすいエラーメッセージを返すことが可能です。

先生と生徒の振り返り会話

生徒

「今回学んだ@PutMappingアノテーションで、データ更新の方法がよくわかりました！HTTP PUTリクエストで更新するんですね。」

先生

「そうですね。PUTリクエストを使うことで、サーバー上のデータを効率的に更新することができます。@RequestParamでIDを指定し、@RequestBodyでデータを受け取ります。」

生徒

「エラーハンドリングも勉強になりました！クライアント側に適切なエラーメッセージを返すことで、API利用者にも優しいですね。」

先生

「その通りです。ResponseStatusExceptionを使うことで、エラー発生時には適切なメッセージを返すことができ、データの整合性も保てます。」

生徒

「またcurlコマンドを使ったリクエストの実行方法も理解できました。実際にAPIを試せるので便利ですね！」

先生

「curlは、APIのリクエストを簡単に送信できるため、開発やテストの際にとても役立ちます。今回の学びを活かして、他のHTTPメソッドでも練習してみましょう。」

生徒

「はい！他のメソッドも試してみます。ありがとうございました！」

この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問／質問を解決します

JavaのSpringで@PutMappingアノテーションは何に使うのですか？初心者でも理解できるように教えてください。

@PutMappingアノテーションは、JavaのSpringフレームワークでHTTP PUTリクエストを処理し、既存データを更新するために使用されます。Spring Bootでユーザー情報を更新したり、REST APIのエンドポイントを作成する際に役立つアノテーションです。データ更新に特化しており、POSTやGETとは目的が異なります。

Springの学習を効率化したい方へ

この記事の内容をもっと深く知るには、以下の入門書が最適です。

Spring Framework超入門をAmazonで見る

元・職業訓練講師が直接指導【Spring Boot実践セミナー】

職業訓練講師が最短攻略！Spring Bootによる「商用バックエンド構築」とDI/AOPの極意。

累計120万PV超の技術メディア運営チームが贈る、商用開発基準の特別カリキュラム

職業訓練講師が最短攻略！Spring Bootによる「商用バックエンド構築」とDI/AOPの極意。

モダンJava開発の事実上の標準Spring Boot。本講座では、その圧倒的利便性の核にある「DI（依存性の注入）」を完全解剖。「設定より規約」を体現した効率的なアーキテクチャ設計を学び、Spring SecurityやJPAなど、現場で必須となるエコシステムの繋ぎ方を60分で濃縮体験します。