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

生徒

「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」を追加しています。クライアント側でレスポンスヘッダーの確認が可能になります。

Spring FrameworkやThymeleafを使った Webアプリ開発の全体像をやさしく理解したい人には、この入門書が定番です。

Spring Framework超入門をAmazonで見る

※ Amazon広告リンク

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の品質やセキュリティを高めることができます。

9. ResponseEntityまとめ：実務での活用ポイント

Spring BootでResponseEntityを使いこなすことで、HTTPレスポンスの制御が格段に柔軟になります。ステータスコード、ヘッダー、ボディの構成を意識することで、クライアントにとって理解しやすく、安全で信頼性の高いAPI設計が可能になります。

実務では、標準的なResponseEntity.ok()の他に、404や403など適切なステータスを活用した設計が求められます。また、ビルダー形式での記述は、コードの見通しをよくし、保守性を高める点でもおすすめです。

まとめ

ResponseEntityで理解するSpring Bootのレスポンス設計

ここまで、Spring BootにおけるResponseEntityの基本から応用までを詳しく見てきました。 ResponseEntityは、HTTPレスポンスを構成するステータスコード、レスポンスヘッダー、レスポンスボディを一つの戻り値としてまとめて扱えるクラスであり、 REST API開発において非常に重要な役割を果たします。単にデータを返すだけでなく、「どのような状態で」「どのような情報を」「どのような意味を持って」返すのかを明確に設計できる点が大きな特徴です。

Spring Bootでは、Controllerのメソッドからオブジェクトを返すだけでも自動的にJSONレスポンスが生成されますが、 ResponseEntityを使うことでHTTPステータスを明示的に指定でき、APIの振る舞いをより正確にクライアントへ伝えることができます。例えば、正常終了時のOK、リソース作成時のCREATED、データ未取得時のNOT FOUND、権限不足時のFORBIDDENなど、状況に応じたレスポンス設計が可能になります。

実務で役立つステータス・ヘッダー・ボディの考え方

実務のAPI開発では、レスポンスの内容がフロントエンドや外部サービスとの連携品質に直結します。 ResponseEntityを活用すれば、レスポンスヘッダーにカスタム情報を付与したり、 Locationヘッダーを用いて新しく作成されたリソースのURLを返したりと、 HTTP仕様に沿った設計が自然に行えるようになります。こうした細やかな設計は、保守性や拡張性の高いシステム構築に欠かせません。

また、例外処理とResponseEntityを組み合わせることで、エラー発生時のレスポンス形式を統一できます。エラーメッセージやステータスコードが整理されていれば、クライアント側の実装もシンプルになり、不具合調査やログ解析の効率も向上します。セキュリティ面においても、認証エラーや認可エラーを適切なHTTPステータスで返すことは非常に重要です。

まとめとしてのサンプルイメージ


@GetMapping("/summary")
public ResponseEntity<String> summarySample() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("X-Summary", "ResponseEntity-Practice");
    return new ResponseEntity<>(
        "ResponseEntityを理解するとAPI設計が明確になります",
        headers,
        HttpStatus.OK
    );
}

このように、ResponseEntityを使えば、レスポンスに意味を持たせた設計が可能になります。単なるデータ返却ではなく、APIとしての意図や状態を正確に伝えることができる点が最大のメリットです。

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

生徒

「ResponseEntityって、ただの戻り値だと思っていましたが、ステータスコードやヘッダーまで含めて設計できるのが大事なんですね。」

先生

「そうですね。Spring BootでAPIを作るなら、 ResponseEntityを使ってHTTPの意味をきちんと表現できるようになることが重要です。」

生徒

「404や403を正しく返すだけで、クライアント側の処理も分かりやすくなりそうです。」

先生

「その通りです。レスポンス設計がしっかりしているAPIは、長く使われても壊れにくく、保守もしやすくなりますよ。」

生徒

「ResponseEntityを意識して使えば、 Spring BootでのREST API開発に自信が持てそうです。」