はじめに
Spring Boot で Web API を作っていると、
ResponseEntity というクラスをよく目にします。
「return で文字列返すだけじゃダメなの？」
「ステータスコードってどうやって変えるの？」
「ヘッダーを付けたいときは？」
そんな疑問を解決してくれるのが ResponseEntity です。
この記事では、ResponseEntity の便利な使い方を
やさしく・実務で役立つ形 で整理していきます。
まずはコードを見て、そこから少しずつ理解していきましょう。
まずはコードを確認
@GetMapping("/hello")
public ResponseEntity<String> hello() {
return ResponseEntity.ok("Hello World");
}このように、
ステータスコード + ボディ + ヘッダー
を自由に返せるのが ResponseEntity の強みです。
ResponseEntity とは
一言でいうと、
「HTTP レスポンスを自由にカスタマイズできるクラス」
です。
- ステータスコード
- レスポンスボディ
- レスポンスヘッダー
これらをまとめて返すことができます。
よく使う便利な書き方
OK（200）を返す
return ResponseEntity.ok("success");ステータスコードを指定する
return ResponseEntity.status(HttpStatus.CREATED).body("created");ヘッダーを付ける
return ResponseEntity
.ok()
.header("X-My-Header", "value")
.body("hello");空レスポンス（204 No Content）
return ResponseEntity.noContent().build();エラーを返す（400 Bad Request）
return ResponseEntity.badRequest().body("invalid request");JSON を返す
return ResponseEntity.ok(new UserResponse("taro", 20));オブジェクトは自動で JSON に変換されます。
実務でよく使うパターン
新規作成（201 Created）
@PostMapping("/users")
public ResponseEntity<UserResponse> create(@RequestBody UserRequest req) {
UserResponse res = service.create(req);
return ResponseEntity.status(HttpStatus.CREATED).body(res);
}更新成功（200 OK）
return ResponseEntity.ok(updatedUser);削除成功（204 No Content）
return ResponseEntity.noContent().build();バリデーションエラー（400 Bad Request）
ControllerAdvice と組み合わせると最強です。
ResponseEntity を使うメリット
ステータスコードを明確にできる
文字列を返すだけでは 「成功なのか？失敗なのか？」 がわかりません。
ResponseEntity なら
- 200
- 201
- 400
- 404
- 500 など、
意図を明確にできます。
ヘッダーを自由に付けられる
認証トークンやページング情報など、
API ではヘッダーが必要になる場面が多いです。
API の設計がきれいになる
Controller の戻り値が統一され、
読みやすく、保守しやすくなります。
あわせて知っておきたいポイント
ResponseEntity はジェネリクス
ResponseEntity<UserResponse>のように、返す型を指定できます。
body() を省略できる場合もある
return ResponseEntity.ok().build();ResponseEntity と例外ハンドリングは相性抜群
ControllerAdvice で
return ResponseEntity.status(404).body(error);のように返せます。
使うときに気をつけたいこと
ステータスコードを正しく使う
- 作成 → 201
- 削除 → 204
- バリデーションエラー → 400
- 認証エラー → 401
- 権限なし → 403
- 見つからない → 404
API の品質が大きく変わります。
ボディが不要なときは noContent()
空文字を返すよりも意図が明確です。
ヘッダーの付けすぎに注意
必要な情報だけに絞ると読みやすくなります。
まとめ
ResponseEntity は、
「HTTP レスポンスを自由にカスタマイズできる便利なクラス」
です。
- ステータスコードを返せる
- ヘッダーを付けられる
- JSON を返すのも簡単
- ControllerAdvice と組み合わせると最強
難しく聞こえますが、
「成功・失敗・ヘッダーをきれいに返すための道具」
と理解できれば十分です。
ResponseEntity を使いこなすと、
API の表現力が一気に上がります。
ステータスコードやヘッダーを丁寧に扱うだけで、
API の品質がぐっと高まります。
あなたの開発が、今日より少しだけ楽になりますように。
レスポンスに気持ちを添えて返せるなんて…ResponseEntity さん、やさしいね。
コメント