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

生徒

「Spring BootでAPIを作っているんですが、レスポンスのステータスやヘッダー、ボディを細かく制御したいです。どうすればいいですか？」

先生

「その場合は、ResponseEntityを使うのが一般的ですね。柔軟にレスポンスを構成できますよ。」

生徒

「レスポンスのステータスやヘッダーって、どうやって設定するんですか？」

先生

「では、ResponseEntityの使い方を詳しく見ていきましょう！」

1. ResponseEntityとは？

Spring BootにおけるResponseEntityは、HTTPレスポンス全体を制御できる便利なクラスです。通常、@RestControllerや@Controllerのメソッドでは、戻り値としてオブジェクトを返すだけでもJSONに変換されてレスポンスされますが、ResponseEntityを使えば、HTTPステータスコード、ヘッダー、ボディの全てを明示的に設定できます。

2. ResponseEntityの基本的な使い方

まずはシンプルな例を見てみましょう。以下のように、ステータスとボディだけを設定するパターンです。


@GetMapping("/hello")
public ResponseEntity<String> hello() {
    return new ResponseEntity<>("こんにちは！", HttpStatus.OK);
}

この例では、HTTPステータス200（OK）と、「こんにちは！」という文字列をレスポンスしています。HttpStatus列挙型を使って、ステータスコードを明示的に指定しています。

3. レスポンスヘッダーを追加する方法

ResponseEntityでは、レスポンスヘッダーも自由に設定できます。たとえば、Content-TypeやLocationなどをカスタムで追加できます。


@GetMapping("/header")
public ResponseEntity<String> withHeader() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("X-Custom-Header", "SpringBoot-Header");
    return new ResponseEntity<>("ヘッダー付きレスポンス", headers, HttpStatus.OK);
}

上記の例では、カスタムヘッダー「X-Custom-Header」を追加しています。クライアント側でレスポンスヘッダーの確認が可能になります。

4. ボディにオブジェクトを返す場合

文字列だけでなく、オブジェクトをボディとして返すことも可能です。Spring BootはJacksonライブラリを使って、自動的にJSONに変換してくれます。


@GetMapping("/user")
public ResponseEntity<User> getUser() {
    User user = new User("太郎", "taro@example.com");
    return ResponseEntity.ok(user);
}

このように、ResponseEntity.ok()メソッドを使うことで、簡単にステータス200を設定しつつオブジェクトを返せます。ボディは自動的にJSONにシリアライズされます。

5. ステータスコードを柔軟に変更する方法

ResponseEntityでは、APIの結果に応じてステータスコードを動的に変更できます。たとえば、データが見つからなかった場合は404を返すことができます。


@GetMapping("/user/{id}")
public ResponseEntity<User> findUser(@PathVariable String id) {
    Optional<User> user = userService.findById(id);
    return user
        .map(ResponseEntity::ok)
        .orElseGet(() -> ResponseEntity.status(HttpStatus.NOT_FOUND).build());
}

このようにすることで、条件に応じて200（OK）や404（Not Found）を返すことができます。API設計において非常に重要なテクニックです。

6. ビルダー形式での記述

実務では、ResponseEntityをビルダー形式で記述する方法がよく使われます。これにより、ヘッダーやステータスの追加が簡潔に書けます。


@GetMapping("/builder")
public ResponseEntity<String> builderStyle() {
    return ResponseEntity
        .status(HttpStatus.CREATED)
        .header("Location", "/new-resource")
        .body("リソースが作成されました");
}

このスタイルは、ヘッダー・ステータス・ボディを順に書けるため読みやすく、メンテナンス性にも優れています。

7. ResponseEntityと例外処理の連携

Spring Bootでは、@ExceptionHandlerと組み合わせてResponseEntityを使うと、例外発生時のレスポンスも整えることができます。


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

このように、例外処理に統一されたHTTPレスポンスを適用することで、フロントエンドやクライアント側での制御がしやすくなります。

8. ResponseEntityとセキュリティの考慮

セキュリティを意識したレスポンス設計も重要です。たとえば、認証エラーや権限不足の場合は、403（Forbidden）や401（Unauthorized）などのステータスコードを返すのが適切です。


@GetMapping("/admin")
public ResponseEntity<String> adminAccess() {
    if (!userService.isAdmin()) {
        return ResponseEntity.status(HttpStatus.FORBIDDEN).body("アクセスが拒否されました");
    }
    return ResponseEntity.ok("管理者ページへようこそ");
}

適切なHTTPステータスを返すことで、APIの品質やセキュリティを高めることができます。