🧠【初心者向け】REST API のレスポンス設計と例外処理をやさしく解説（図解あり）
REST API を実務で書くときに
初心者が最もつまずくのが レスポンス設計と例外処理 です。
- エラー時は何を返せばよい？
- 200 と 400 と 500 の違い？
- 例外が起きたとき、どこでキャッチすればいい？
- @ExceptionHandler の役割は？
- バリデーションエラーはどう返す？
- 共通レスポンス形式ってどう作る？
これらはシステム全体の品質に直結する重要ポイントです。
この記事では
初心者向けのやさしい解説 × 実務に使える設計指針 × Spring Boot の深掘り
を交えて、“REST API の土台” を作れるように解説します。
✨ 結論
✔ 成功レスポンスとエラーレスポンスは形式を統一する
✔ HTTPステータスコードは “意味” を理解して正しく使う
✔ 例外は Controller でキャッチしない（ControllerAdvice が担当）
✔ バリデーションは @Valid + BindingResult + グローバルハンドラ
✔ Spring Boot では例外ハンドリングを “層” で整理するのが正解
REST API の基本：成功レスポンスは「統一形式」にする
REST API で最も重要なのは
「成功・失敗どちらも同じ形式で返すこと」
統一された形式なら、呼び出す側もパースが簡単です。
成功レスポンスの例（共通フォーマット）
{
"status": "success",
"data": {
"id": 123,
"name": "Alice"
}
}
エラーレスポンスの例
{
"status": "error",
"message": "Invalid user ID",
"code": "USER_001"
}
HTTPステータスコードを正しく使う（初心者がつまずくポイント）
代表的なステータスコードと用途👇
| ステータス | 用途 |
|---|---|
| 200 | 正常系 |
| 201 | 作成成功（POST） |
| 400 | バリデーションエラー |
| 401 | 認証エラー |
| 403 | 権限不足 |
| 404 | リソース未発見 |
| 409 | 競合（重複など） |
| 500 | サーバー内部エラー |
🔹 図解（短線版）
200 = 正常
400 = リクエスト不備
500 = サーバーの問題
覚えるのはこれだけでも十分。
Spring での例外処理の原則（重要）
Spring では、例外は Controller で直接キャッチしない のが原則。
代わりに👇を使う。
- @ControllerAdvice
- @ExceptionHandler
@ControllerAdvice の役割
全コントローラ共通で
例外をハンドリングする仕組み。
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(NotFoundException.class)
public ResponseEntity<?> handleNotFound(NotFoundException e) {
return ResponseEntity.status(404)
.body(new ErrorResponse("USER_001", e.getMessage()));
}
}
例外ハンドリングは「層」で整理するとスッキリする
🔹 図解（短線版）
Controller
↑ 例外は上がってくる
Service
↑ ここでは必要に応じて例外をラップ
Repository
↑ DB例外はここから
✔ Controller → 例外を受け取る（返却の責務）
✔ Service → 業務例外を定義
✔ Repository → DB例外を投げる
バリデーションエラー（@Valid）の扱い
よくある例👇
@PostMapping("/users")
public Response create(@Valid @RequestBody UserForm form) {
...
}
エラー時は BindingResult で取得可能。
Spring Boot の内部構造（深掘り）
更に理解を深めるために
「内部で何が起きているか」も図解します。
① DispatcherServlet が例外をキャッチ
Spring MVC 全体の中心。
② HandlerExceptionResolver が適切な ExceptionHandler を探す
複数の Resolver が存在。
③ @ControllerAdvice がマッチしたらそこで処理
例外 → 適切な処理 → HTTPレスポンスへ変換。
④ 最終的には HttpMessageConverter が JSON にシリアライズ
Jackson が担当。
実務で役立つ REST API 例外設計のベストプラクティス
✔ “クライアントが扱いやすい” エラー形式に統一
✔ エラーコード（USER_001 など）を必ずつける
✔ API の返却値は成功・失敗どちらも共通形式
✔ スタックトレースはログにだけ出す
✔ 例外は ControllerAdvice でまとめる
ここまでのまとめ（初心者向け）
- REST API は成功・失敗の形式を統一する
- HTTPステータスコードの意味を理解する
- @ControllerAdvice で例外処理を一元化
- バリデーションは @Valid とハンドラー
- 内部構造は DispatcherServlet → Resolver → Handler
Deep Friendly Tech の一言（後書き）
REST API の例外設計は
“コード品質の差が一番出るポイント” です。
この設計が整っているだけで
使いやすい API / 事故が少ない API / 保守しやすい API
の3つが一気に実現します。
ぜひ今日からあなたの API でも活用してみてください。
コメント