@ResponseStatusの使い方と徹底解説！【初心者向け】

こんにちは！今回は、Spring FrameworkでHTTPステータスコードを簡単に指定できるアノテーション、@ResponseStatusについて詳しく解説します。@ResponseStatusを使えば、例外処理やAPIレスポンスのステータスコードを柔軟に管理できるようになります。

@ResponseStatusとは？

@ResponseStatusとは、

「HTTPレスポンスのステータスコードを設定するためのアノテーション」

のことです。たとえば、リクエストが正常に処理された場合に 200 OK を返したり、リソースが見つからなかった場合に 404 Not Found を返したりするのに使用されます。

これを使用することで、より直感的で明確なAPI設計が可能になります。特に例外処理と組み合わせることで、エラーハンドリングがシンプルになり、コードの可読性も向上します。

@ResponseStatusの基本的な使い方

まずは、簡単なコード例を見てみましょう。特定のユーザーを取得しようとして見つからなかった場合に 404 Not Found を返すケースを紹介します。

例1：例外クラスで使用する場合

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

このコードでは、UserNotFoundException がスローされると自動的に 404 Not Found ステータスが返されます。

コントローラーでの使用例

@GetMapping("/users/{id}")
public User getUserById(@PathVariable Long id) {
    return userService.findUserById(id)
            .orElseThrow(() -> new UserNotFoundException("User not found"));
}

この例では、指定したIDのユーザーが見つからなければ UserNotFoundException を投げることで、クライアントに 404 Not Found を返しています。

@ResponseStatusの引数について

@ResponseStatusは以下のような引数を使用できます。

value または code 属性：返すHTTPステータスコードを指定します（デフォルトは HttpStatus.INTERNAL_SERVER_ERROR）。
reason 属性：ステータスコードに付随する理由を設定できます（HTTPレスポンスのボディには含まれません）。

例2：valueとreasonの使用

@ResponseStatus(value = HttpStatus.BAD_REQUEST, reason = "Invalid User Data")
public class InvalidUserDataException extends RuntimeException {
}

この設定により、InvalidUserDataException がスローされると 400 Bad Request と共に “Invalid User Data” という理由が返されます。

@ResponseStatusの応用編

@ResponseStatusを活用することで、REST APIのエラーレスポンスをさらに柔軟に制御できます。ここでは、少し高度な使い方を紹介します。

1. デフォルトメッセージのカスタマイズ

@ResponseStatusの reason 属性を使用すると、カスタムエラーメッセージを設定できます。ただし、reason 属性は レスポンスボディには含まれない ことに注意が必要です。

@ResponseStatus(HttpStatus.FORBIDDEN)
public class AccessDeniedException extends RuntimeException {
    public AccessDeniedException() {
        super("You do not have permission to access this resource");
    }
}

2. @ExceptionHandlerとの併用

@ResponseStatusを使わずに、@ExceptionHandler を利用して柔軟なエラーハンドリングを行う方法もあります。

@ExceptionHandler(UserNotFoundException.class)
public ResponseEntity<String> handleUserNotFound(UserNotFoundException ex) {
    return ResponseEntity.status(HttpStatus.NOT_FOUND)
                         .body(ex.getMessage());
}

この方法では、レスポンスボディにエラーメッセージを含めることができます。

3. コントローラー全体に適用する（@ControllerAdvice）

複数のコントローラーで共通のエラーハンドリングを行いたい場合、@ControllerAdvice と組み合わせると便利です。

@ControllerAdvice
public class GlobalExceptionHandler {

    @ResponseStatus(HttpStatus.NOT_FOUND)
    @ExceptionHandler(UserNotFoundException.class)
    public void handleNotFound() {
        // レスポンスボディは返さない
    }
}

よく使われるHTTPステータスコード一覧

200 OK：リクエストが正常に処理された。
201 Created：新しいリソースが正常に作成された。
204 No Content：処理は成功したが、返すコンテンツがない。
400 Bad Request：不正なリクエスト。
401 Unauthorized：認証が必要。
403 Forbidden：アクセス権がない。
404 Not Found：リソースが見つからない。
409 Conflict：競合が発生した（例えば重複データの挿入）。
500 Internal Server Error：サーバー内部でエラーが発生した。

@ResponseStatusの使用上の注意点

レスポンスボディにメッセージを含める場合は注意
- reason 属性を設定してもレスポンスボディには含まれません。ボディにメッセージを含めたい場合は、@ExceptionHandlerを使用しましょう。
カスタム例外の推奨
- @ResponseStatusはカスタム例外クラスと組み合わせることで、より直感的に利用できます。
REST APIの設計に合わせたステータスコードを使用
- 適切なHTTPステータスコードを選ぶことで、APIの利用者に対して明確なレスポンスを提供できます。