JavaのSpring Bootでの@ResponseEntityアノテーションの使い方を初心者向けに徹底解説！

1. @ResponseEntityとは？

1. @ResponseEntityとは？

JavaのSpring Bootフレームワークでは、@ResponseEntityアノテーションを使うことで、サーバーからクライアントに返すHTTPレスポンスの中身を細かくコントロールできます。通常のコントローラーメソッドは、メソッドの戻り値をそのままレスポンスボディとして返し、ステータスコードは自動的に「200 OK」になりますが、@ResponseEntityを使うと、ステータスコード、レスポンスボディ、ヘッダーを自分の意図どおりに設定できます。

もう少しかみ砕いて言うと、@ResponseEntityは「どんな結果を、どんな状態で返すか」をひとまとめにして表現するための入れ物のようなものです。例えば「処理が成功したからメッセージを返したい」「エラーが起きたのでエラーメッセージとエラー用のステータスコードを返したい」といったときに、この入れ物の中に「文字列やオブジェクト」「ステータスコード」「必要ならヘッダー情報」を詰め込んで返すイメージです。

初心者のうちは、まず「ResponseEntity<型>という形で、どんなデータを返すかを指定する」「第2引数にHttpStatus.OKなどのステータスコードを渡せる」という二つを覚えておくと理解しやすくなります。これが分かってくると、Spring BootでREST APIを作るときに、「成功」「失敗」「データなし」といった状態をきちんとHTTPレスポンスとして表現できるようになり、実践的なWebアプリケーション開発に一歩近づけます。

2. @ResponseEntityの基本的な使い方

2. @ResponseEntityの基本的な使い方

ここでは、@ResponseEntityを実際にどう書くのか、いちばんシンプルな例で確認してみましょう。まずは「/hello」というパスにアクセスしたときに、メッセージとHTTPステータスコードをセットで返す基本パターンです。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ExampleController {

    @GetMapping("/hello")
    public ResponseEntity<String> sayHello() {
        return new ResponseEntity<>("Hello, World!", HttpStatus.OK);
    }
}

このコードでは、/helloというURLにブラウザからアクセスすると、「Hello, World!」という文字列と一緒にHTTPステータスコード200（OK）が返されます。ResponseEntity<String>という戻り値の型は、「文字列をボディとして持つHTTPレスポンスを返します」という意味だと考えると分かりやすいです。

new ResponseEntity<>("Hello, World!", HttpStatus.OK)の第1引数がクライアントに返すメッセージ（レスポンスボディ）、第2引数がステータスコードです。つまりこの1行だけで、「内容はこのテキスト」「結果は成功（OK）」という情報をまとめて返していることになります。ブラウザの開発者ツールでネットワークタブを開いてみると、ステータスが「200 OK」になっていることも確認できるので、Spring BootとHTTPレスポンスの関係を体感しながら学ぶことができます。

3. HTTPステータスコードの設定

3. HTTPステータスコードの設定

@ResponseEntityでは、さまざまなHTTPステータスコードを設定できます。例えば、リクエストが正常に処理されなかった場合には、HttpStatus.BAD_REQUESTを返すことができます。

@GetMapping("/error")
public ResponseEntity<String> handleError() {
    return new ResponseEntity<>("Bad Request", HttpStatus.BAD_REQUEST);
}

この場合、クライアントには「Bad Request」というメッセージとともにHTTPステータス400が返されます。

4. レスポンスヘッダーのカスタマイズ

4. レスポンスヘッダーのカスタマイズ

HTTPレスポンスにはヘッダーを追加することも可能です。ヘッダーには、メタデータや追加情報を含めることができます。

import org.springframework.http.HttpHeaders;

@GetMapping("/custom-header")
public ResponseEntity<String> customHeader() {
    HttpHeaders headers = new HttpHeaders();
    headers.add("Custom-Header", "MyValue");
    return new ResponseEntity<>("Header added!", headers, HttpStatus.OK);
}

この例では、Custom-Headerという独自のヘッダーがレスポンスに追加されます。

5. ボディの内容をカスタマイズする方法

5. ボディの内容をカスタマイズする方法

通常、@ResponseEntityは文字列だけでなく、オブジェクトも返すことができます。JSON形式のデータを返す場合、Spring Bootは自動的にオブジェクトをシリアライズしてくれます。

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;

public class User {
    private String name;
    private int age;

    // コンストラクタとゲッター・セッター
    public User(String name, int age) {
        this.name = name;
        this.age = age;
    }
    public String getName() { return name; }
    public int getAge() { return age; }
}

@GetMapping("/user")
public ResponseEntity<User> getUser() {
    User user = new User("John", 30);
    return new ResponseEntity<>(user, HttpStatus.OK);
}

このコードでは、/userエンドポイントにアクセスすると、以下のようなJSONデータが返されます。

{
    "name": "John",
    "age": 30
}

6. エラーハンドリングと@ResponseEntity

6. エラーハンドリングと@ResponseEntity

Spring Bootでは、@ResponseEntityを使ってエラーを適切に返すことも重要です。例えば、リソースが見つからなかった場合に404エラーを返す方法です。

@GetMapping("/not-found")
public ResponseEntity<String> notFound() {
    return new ResponseEntity<>("Resource not found", HttpStatus.NOT_FOUND);
}

この例では、リクエストされたリソースが見つからない場合に、HTTPステータス404（Not Found）が返されます。

7. まとめ

7. まとめ

今回の記事では、JavaのSpring Bootで使用する@ResponseEntityアノテーションについて学びました。@ResponseEntityを使用すると、HTTPレスポンスの内容を細かくカスタマイズできるため、APIの設計や開発においてとても便利です。特に、ステータスコードの設定やレスポンスヘッダーの追加、オブジェクトを返す際のシリアライズの処理など、幅広い用途に対応できます。

以下は、今回学んだ重要なポイントです。

• @ResponseEntityを使うことで、HTTPステータスコードを自由に設定可能。
• レスポンスヘッダーを追加して、カスタムデータを返すことができる。
• オブジェクトを返す場合、自動的にJSON形式にシリアライズされる。
• エラーハンドリングにも有効で、適切なステータスコードを返すことができる。

以下は、@ResponseEntityの様々な使い方をまとめたサンプルプログラムです。

import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SummaryController {

    // ステータス200（OK）の例
    @GetMapping("/success")
    public ResponseEntity<String> successResponse() {
        return new ResponseEntity<>("Success!", HttpStatus.OK);
    }

    // カスタムヘッダーの追加
    @GetMapping("/header-example")
    public ResponseEntity<String> headerExample() {
        HttpHeaders headers = new HttpHeaders();
        headers.add("X-Example-Header", "HeaderValue");
        return new ResponseEntity<>("Header added", headers, HttpStatus.OK);
    }

    // ステータス404（Not Found）の例
    @GetMapping("/not-found-example")
    public ResponseEntity<String> notFoundExample() {
        return new ResponseEntity<>("Resource not found", HttpStatus.NOT_FOUND);
    }

    // JSONオブジェクトのレスポンス
    @GetMapping("/json-example")
    public ResponseEntity<User> jsonExample() {
        User user = new User("Alice", 25);
        return new ResponseEntity<>(user, HttpStatus.OK);
    }

    // エラーハンドリングの例
    @GetMapping("/bad-request-example")
    public ResponseEntity<String> badRequestExample() {
        return new ResponseEntity<>("Bad request error", HttpStatus.BAD_REQUEST);
    }
}

このコードには、ステータスコード、カスタムヘッダー、エラーハンドリング、JSONレスポンスの例が含まれています。実際の開発では、これらを組み合わせてAPIの挙動をカスタマイズすることが一般的です。

この記事を読んだ人からの質問

この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問／質問を解決します

@ResponseEntityを使うと何ができますか？

@ResponseEntityを使うと、HTTPレスポンスのステータスコード、ヘッダー、ボディを細かく設定できます。これにより、APIのレスポンスをクライアントの要求に合わせて柔軟にカスタマイズできます。

@ResponseEntityと通常のコントローラーのレスポンスの違いは何ですか？

通常のコントローラーはデフォルトでHTTPステータス200（OK）を返しますが、@ResponseEntityを使うと、ステータスコードやヘッダーをカスタマイズできる点が大きな違いです。

ステータスコードを設定する方法を教えてください。

@ResponseEntityの第2引数にHttpStatusを指定することで、ステータスコードを設定できます。例えば、HttpStatus.OKやHttpStatus.BAD_REQUESTなどを使用します。

レスポンスヘッダーを追加するにはどうすればいいですか？

HttpHeadersクラスを使ってヘッダーを作成し、それを@ResponseEntityの引数に渡すことでレスポンスヘッダーを追加できます。

JSON形式でデータを返すにはどうしたらいいですか？

@ResponseEntityでオブジェクトを返すと、Spring Bootが自動的にそのオブジェクトをJSON形式にシリアライズしてレスポンスを生成します。

エラーが発生した場合、クライアントに適切なエラーメッセージを返す方法は？

@ResponseEntityを使って、エラーメッセージとHTTPステータスコード（例えばHttpStatus.NOT_FOUNDやHttpStatus.BAD_REQUEST）を設定することで、クライアントに適切なエラーメッセージを返せます。

@ResponseEntityを使うとパフォーマンスに影響はありますか？

@ResponseEntity自体が軽量なため、通常のレスポンスに比べて大きなパフォーマンス差はありません。ただし、複雑な処理を追加するとパフォーマンスに影響する可能性があります。

Spring Bootで@ResponseEntityを使うのはどのような場面が適していますか？

カスタムレスポンスが必要な場合や、エラーメッセージを詳細に設定する必要がある場合、またクライアントと明確な通信を行いたい場合に適しています。

@ResponseEntityを使うとき、オブジェクトの中にネストされたデータもJSONとして返せますか？

はい、Spring Bootはオブジェクト内のネストされたデータも自動的にシリアライズしてJSONとして返すことができます。

HTTPステータスコードの設定やヘッダーの追加を行う代わりに、通常の方法で対応することはできますか？

通常の方法でも可能ですが、コードが煩雑になりやすいため、@ResponseEntityを使う方がシンプルかつ管理しやすい設計になります。

元・職業訓練講師が直接指導【Spring Boot実践セミナー】

職業訓練講師が最短攻略！Spring Bootによる「商用バックエンド構築」とDI/AOPの極意。

累計120万PV超の技術メディア運営チームが贈る、商用開発基準の特別カリキュラム

職業訓練講師が最短攻略！Spring Bootによる「商用バックエンド構築」とDI/AOPの極意。

モダンJava開発の事実上の標準Spring Boot。本講座では、その圧倒的利便性の核にある「DI（依存性の注入）」を完全解剖。「設定より規約」を体現した効率的なアーキテクチャ設計を学び、Spring SecurityやJPAなど、現場で必須となるエコシステムの繋ぎ方を60分で濃縮体験します。

60分集中ワークショップ内容

【つくるもの】
商用利用を想定した「REST APIベースのタスク管理システム」を構築。Spring Data JPAによる高速DB連携から、ビジネスロジックの分離、堅牢なバリデーション実装まで、Webアプリの「正解の型」を最短距離で作り上げます。

【開発環境】
Spring Initializrでのプロジェクト生成から、Docker環境との連携まで。LombokやSpring Boot DevToolsを駆使した、実務10年PLが実践する「開発効率を極限まで高める」プロのセットアップを伝授します。

この60分で得られる3つの革新スキル

1. DIコンテナの本質的な理解と疎結合設計

なぜSpringが選ばれるのか？Bean管理の仕組みを理解し、保守・テストが容易な「プロの設計」を習得します。

2. Spring Data JPAによる高速データアクセス

リポジトリ層を抽象化。SQLを最小限に抑えつつ、パフォーマンスを最大化させるクエリ設計の勘所を学びます。

3. アノテーション駆動開発による開発速度の向上

冗長なコードを排除。Springが提供するアノテーションを使いこなし、ビジネスロジックに集中する技法を伝授します。

※本講座は、Javaの基本を終え、即戦力エンジニアを目指す方のための「ハイクラス・フレームワーク実践講座」です。商用レベルの技術習得を、職業訓練講師の実績を持つプロが全力でリードします。

Spring Bootセミナーの詳細・予約はこちら

現場の「実務基準」が手に入る

20名規模のプロジェクトリーダー（PL）が、トラブルを防ぐ実装ノウハウを直接伝授します。