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

生徒

「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ステータスだけでなく、レスポンスボディやヘッダーもカスタマイズ可能です。

7. REST APIでのHTTPエラー制御の実践ポイント

Spring BootでREST APIを開発する際には、適切なHTTPステータスコードを返すことが非常に重要です。以下のポイントを意識しましょう。

リソースが見つからないときは404 Not Found
リクエストが不正なときは400 Bad Request
権限がない場合は403 Forbidden
サーバー側の例外は500 Internal Server Error

これらを@ResponseStatusやResponseStatusExceptionで適切に返すことで、API設計が明確になり、クライアント側のバグも減ります。

8. よくある失敗と注意点

初心者がよく陥るミスとして、「@ResponseStatusをつけ忘れていて、デフォルトで500 Internal Server Errorになってしまう」パターンがあります。

また、ResponseStatusExceptionを使う際に、HttpStatusがnullになっていると例外の発火に失敗することがあります。

このようなトラブルを避けるためには、使用するステータスコードとその用途をしっかり理解しておくことが大切です。

まとめ

今回はSpringにおけるHTTPステータス制御の基本として、ResponseStatusアノテーションとResponseStatusExceptionの使い方を体系的に整理しました。Spring BootやSpring MVCでREST APIを開発する際には、例外処理とHTTPステータスコードの設計が非常に重要です。単にエラーを発生させるだけではなく、クライアントに対して適切なHTTPステータスを返却することで、APIの可読性と保守性が大きく向上します。

ResponseStatusは例外クラスに直接HTTPステータスコードを付与できる仕組みであり、特定のビジネス例外を明確に分類したい場合に適しています。例えばリソース未存在時の例外や認可エラーなど、意味が固定された例外に対して活用することで、アプリケーション全体の設計が整理されます。一方でResponseStatusExceptionは、コントローラ内部で動的にHTTPステータスを指定できる柔軟な方法です。条件分岐の結果に応じてBadRequestやNotFoundを切り替えるようなケースでは特に有効です。

またControllerAdviceやExceptionHandlerと組み合わせることで、Springアプリケーション全体の例外処理を一元管理できます。これによりREST APIのエラーレスポンス形式を統一し、フロントエンドや外部クライアントとの連携を円滑に進められます。HTTPステータスコードの設計はAPI品質そのものに直結するため、四百番台と五百番台の違いを正確に理解し、状況に応じて使い分けることが重要です。

以下は、これまで学習した内容をまとめたサンプルプログラムです。ResponseStatusとResponseStatusExceptionを組み合わせた実装例として確認してください。


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

@RestController
@RequestMapping("/api")
public class SampleController {

    @GetMapping("/sample/{id}")
    public String getSample(@PathVariable String id) {

        if (id == null || id.isEmpty()) {
            throw new InvalidParameterException("識別子が未入力です");
        }

        if (id.equals("0")) {
            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "対象データが存在しません");
        }

        return "正常に処理されました";
    }
}

上記のように設計することで、入力値の不正はBadRequestとして処理され、データ未存在はNotFoundとして返却されます。Spring BootでのREST API開発では、このようなHTTPステータス制御の考え方を理解しておくことが必須です。適切なエラーハンドリングはユーザー体験を高めるだけでなく、デバッグや保守運用の効率化にも直結します。


正常に処理されました

今回の内容を通して、Springの例外処理設計、HTTPステータスコード制御、ResponseStatusとResponseStatusExceptionの違い、ControllerAdviceとの連携方法までを一通り確認しました。これらを理解しておくことで、実践的なWebアプリケーション開発において堅牢なエラー処理を実装できるようになります。

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

生徒

今日はSpringのResponseStatusとResponseStatusExceptionの違いを学びました。HTTPステータスコードを正しく返すことがREST API設計で重要だと理解できました。

先生

その通りです。Spring BootでAPIを作る場合、例外処理とHTTPステータス制御は基本中の基本です。四百番台と五百番台の違いを説明できますか。

生徒

四百番台はクライアント側のリクエストに問題がある場合で、五百番台はサーバー内部のエラーでした。状況に応じてBadRequestやNotFoundを使い分ける必要があります。

先生

よく理解できていますね。ResponseStatusは例外クラスに固定的に付与する方法で、ResponseStatusExceptionは動的に指定できる方法でしたね。

生徒

はい。さらにControllerAdviceを使えばアプリケーション全体で例外を統一管理できることも分かりました。Spring MVCとREST API開発ではとても重要だと感じました。

先生