はじめに
Spring Boot で Web API を作っていると、
「例外がそのまま返ってしまう」
「エラー時のレスポンスを統一したい」
「RestController の中が try-catch だらけになる」
といった悩みが出てきます。
そんなときに役立つのが
@ControllerAdvice と @ExceptionHandler
による例外ハンドリングです。
この記事では、この仕組みを
やさしく・実務で役立つ形 で整理していきます。
まずはコードを見て、そこから少しずつ理解していきましょう。
まずはコードを確認
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(IllegalArgumentException.class)
public ResponseEntity<String> handleIllegalArgument(IllegalArgumentException e) {
return ResponseEntity.badRequest().body(e.getMessage());
}
}このコードを用意しておくだけで、
アプリ全体で IllegalArgumentException が発生したときに
統一されたレスポンスを返せるようになります。
コードのしくみを解説
@ControllerAdvice とは
一言でいうと、
「アプリ全体の例外処理をまとめる場所」
です。
- 全コントローラに適用される
- 共通の例外ハンドリングを定義できる
- コントローラのコードをスッキリさせられる
というメリットがあります。
@ExceptionHandler とは
一言でいうと、
「この例外が発生したら、このメソッドで処理してください」
という指示です。
例：
- IllegalArgumentException
- NullPointerException
- CustomException（独自例外）
など、好きな例外をキャッチできます。
もう少し実務寄りの例を見てみる
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity<Map<String, Object>> handleException(Exception e) {
Map<String, Object> body = new HashMap<>();
body.put("error", "Internal Server Error");
body.put("message", e.getMessage());
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(body);
}
}このように JSON 形式で返すこともできます。
API の品質がぐっと上がります。
あわせて知っておきたいポイント
RestControllerAdvice という便利アノテーション
@RestControllerAdviceこれは
@ControllerAdvice + @ResponseBody
のセットです。
API 開発ではこちらを使うことが多いです。
例外クラスを作るとさらに整理できる
独自の例外クラスを作ると、 「どんなエラーなのか」が明確になります。
例：
public class UserNotFoundException extends RuntimeException {
public UserNotFoundException(String message) {
super(message);
}
}ステータスコードを適切に返す
- 400 Bad Request
- 404 Not Found
- 500 Internal Server Error
など、状況に応じて返すと API としての品質が上がります。
使うときに気をつけたいこと
例外をキャッチしすぎない
Exception を広くキャッチしすぎると、
本来気づくべきエラーに気づけなくなることがあります。
ログは適切に残す
例外ハンドリングはレスポンスを整えるだけでなく、
ログを残す場所としても重要です。
コントローラに try-catch を書かない
例外ハンドリングを ControllerAdvice にまとめることで、
コントローラのコードが読みやすくなります。
まとめ
@ControllerAdvice は、
「アプリ全体の例外処理をまとめる仕組み」 です。
- @ExceptionHandler で例外ごとの処理を定義
- JSON 形式で統一したレスポンスを返せる
- コントローラのコードがスッキリする
難しく聞こえますが、
「例外が起きたらここでまとめて処理する場所」
と理解できれば十分です。
例外ハンドリングを整えると、API の品質が一気に上がります。
開発中のストレスも減り、保守性も高まります。
あなたの開発が、今日より少しだけ楽になりますように。
エラーが起きても、やさしく受け止めてくれる場所があるって安心だね
コメント