はじめに
Spring Boot で Web API を作っていると、
ResponseEntity というクラスをよく見かけます。
「return で文字列を返すだけじゃダメなの？」
「ResponseEntity を使うと何が嬉しいの？」
「ステータスコードってどうやって返すの？」
そんな疑問を持つ方も多いと思います。
この記事では、ResponseEntity の基本を
やさしく・実務で役立つ形
で整理していきます。
まずはコードを見て、そこから少しずつ理解していきましょう。
まずはコードを確認
@GetMapping("/hello")
public ResponseEntity<String> hello() {
return ResponseEntity.ok("Hello World");
}このコードでは、
HTTP ステータス 200 OK とともに
“Hello World” を返しています。
コードのしくみを解説
ResponseEntity とは
一言でいうと、
「ステータスコード・ヘッダー・ボディをまとめて返せる便利な入れ物」
です。
通常の戻り値（String やオブジェクト）では
「ボディ」しか返せませんが、
ResponseEntity を使うと
- ステータスコード
- レスポンスヘッダー
- レスポンスボディ
を自由に組み立てることができます。
どうして必要なのか
API では、
「成功」「失敗」「権限なし」「データがない」
など、状況に応じてステータスコードを返す必要があります。
ResponseEntity を使うと、 その制御がとても簡単になります。
よく使う ResponseEntity の書き方
成功レスポンス
return ResponseEntity.ok("success");ステータスコードを指定
return ResponseEntity.status(HttpStatus.CREATED).body("created");ヘッダーを追加
return ResponseEntity
.ok()
.header("X-Custom-Header", "value")
.body("hello");JSON を返す
return ResponseEntity.ok(new User("taro", 20));
オブジェクトを返すと自動で JSON に変換されます。
あわせて知っておきたいポイント
ResponseEntity は「柔軟なレスポンス」を作るための道具
- ステータスコード
- ヘッダー
- ボディ
これらを自由に組み合わせられるため、
API の表現力が一気に広がります。
例外ハンドリングと相性が良い
ControllerAdvice と組み合わせると、
統一されたエラーレスポンスを返せます。
例：
return ResponseEntity
.status(HttpStatus.BAD_REQUEST)
.body(Map.of("error", "Invalid parameter"));ResponseEntity を返すか迷ったら
- ステータスコードを変えたい
- ヘッダーを付けたい
- エラー時のレスポンスを整えたい
こういうときは ResponseEntity を使うとスッキリします。
使うときに気をつけたいこと
なんでも ResponseEntity にしなくてもよい
単純な成功レスポンスなら
return "hello";でも問題ありません。
返す型を統一すると読みやすい
プロジェクト内で
「成功も失敗も ResponseEntity に統一する」
などのルールを決めると保守性が上がります。
ボディに null を返さない
API の利用者が困るため、
空の場合は空オブジェクトやメッセージを返すのが実務的です。
まとめ
ResponseEntity は、
「ステータスコード・ヘッダー・ボディをまとめて返せる便利な入れ物」
です。
- ステータスコードを自由に返せる
- ヘッダーを追加できる
- JSON も簡単に返せる
- 例外ハンドリングと相性が良い
難しく聞こえますが、
「レスポンスを自由に組み立てるための道具」
と理解できれば十分です。
ResponseEntity を使いこなせるようになると、
API の表現力がぐっと広がります。
あなたの開発が、今日より少しだけ楽になりますように。
レスポンスを好きな形に包んで返せるなんて…プレゼントみたいでかわいいね。
コメント