Springの@ResponseStatusとResponseStatusExceptionの使い方を徹底解説！初心者向けHTTPステータス制御ガイド

@ResponseStatus と ResponseStatusException：HTTPステータスの付け方

教材紹介 Spring Boot 学習のおすすめ教材

Spring Bootを使ったWebアプリケーション開発を、環境構築から実践まで一通り学びたい方には、定評のある入門書が参考になります。

Spring Boot 3 プログラミング入門をAmazonで見る

※ Amazon広告リンク

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

生徒

「Springで例外が起きたときに、HTTPステータスを自分で指定したいんですけど、どうすればいいんですか？」

先生

「それなら、@ResponseStatusやResponseStatusExceptionを使うと、簡単にステータスコードを設定できますよ。」

生徒

「それってどういう違いがあるんですか？使い分けも知りたいです！」

先生

「じゃあ、それぞれの特徴と使い方を詳しく見ていきましょう。」

1. SpringでHTTPステータスを制御する理由とは？

Webアプリケーション開発では、例外が発生した際に適切なHTTPステータスコードを返すことが重要です。Springでは、REST APIやMVCコントローラでのエラーレスポンスに404 Not Foundや400 Bad Requestなどのステータスを返すために、@ResponseStatusやResponseStatusExceptionを活用します。

これにより、クライアント側での処理がわかりやすくなり、ユーザーエクスペリエンスやAPI設計の品質が向上します。

2. @ResponseStatusアノテーションの基本

@ResponseStatusは、Springで例外クラスにHTTPステータスコードを割り当てるためのアノテーションです。独自の例外クラスを作成して、そのクラスに対してステータスを指定します。

以下のように使います：


@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
    public ResourceNotFoundException(String message) {
        super(message);
    }
}

この例では、ResourceNotFoundExceptionが発生すると、自動的に404 Not Foundとしてクライアントに返されます。

3. @ResponseStatusを使ったコントローラ例

実際のSpring MVCコントローラでの使用例を見てみましょう。


@GetMapping("/user/{id}")
public String getUser(@PathVariable String id) {
    if (!userService.exists(id)) {
        throw new ResourceNotFoundException("ユーザーが見つかりませんでした");
    }
    return "user-detail";
}

このように、ビジネスロジックで条件をチェックし、該当しない場合に@ResponseStatus付きの例外をスローすることで、明確なエラー処理が実現できます。

4. ResponseStatusExceptionの基本と使い方

ResponseStatusExceptionは、例外クラスをわざわざ作らずに、任意のタイミングでステータスコードを動的に指定できる便利なクラスです。

例えば、以下のように記述できます：


@GetMapping("/product/{id}")
public String getProduct(@PathVariable String id) {
    if (!productService.exists(id)) {
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, "商品が存在しません");
    }
    return "product-detail";
}

ResponseStatusExceptionはSpring 5から追加された仕組みで、より柔軟にHTTPエラーを返せるのが特徴です。

5. 独自メッセージ付きのエラーレスポンス

クライアントに対して、ステータスコードだけでなくエラーメッセージも返したい場合、ResponseStatusExceptionにメッセージを含めることで対応できます。これは、REST APIでのエラー診断に非常に役立ちます。

例えば：


throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "パラメータが不正です");

このように記述すれば、HTTPステータスが400で、メッセージとしてパラメータが不正ですがレスポンスボディに含まれるようになります。

6. ControllerAdviceと併用する方法

@ResponseStatusとResponseStatusExceptionは単体でも使えますが、@ControllerAdviceと@ExceptionHandlerを使って、アプリケーション全体の例外を一括管理することも可能です。

例えば、以下のように記述できます：


@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ResourceNotFoundException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.NOT_FOUND);
    }
}

この方法では、HTTPステータスだけでなく、レスポンスボディやヘッダーもカスタマイズ可能です。