@ControllerAdviceと@ExceptionHandler
例外をグローバルに処理します
「@ControllerAdviceと@ExceptionHandler」はCoddyKit上の無料Spring Boot 4 Microservices & REST APIsレッスンです。 これはレッスン3/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはSpring Boot 4 Microservices & REST APIs学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Spring Boot 4 Microservices & REST APIsコースには全4レッスンが含まれています。
このレッスンの一部はまだ翻訳されておらず、英語で表示されています。
The Problem with Scattered Try/Catch
Handling errors with try/catch in every controller duplicates code and produces inconsistent responses. Spring MVC offers a centralized model: exception handlers that turn exceptions into clean HTTP responses.
Local @ExceptionHandler
A method annotated @ExceptionHandler inside a controller handles the listed exception types for that controller. It maps an exception to a response.
@RestController
public class OrderController {
@ExceptionHandler(OrderNotFoundException.class)
public ResponseEntity<String> handleNotFound(OrderNotFoundException ex) {
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
}
}Going Global with @ControllerAdvice
@ControllerAdvice (or @RestControllerAdvice) hosts exception handlers that apply across all controllers. This centralizes error handling in one class.
@RestControllerAdvice
public class GlobalExceptionHandler {
// handlers shared by every controller
}Handling a Domain Exception
Define handlers for your own exceptions, returning the right status and a structured body. The same logic now serves every endpoint.
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
@ResponseStatus(HttpStatus.NOT_FOUND)
public ApiError notFound(ResourceNotFoundException ex) {
return new ApiError("NOT_FOUND", ex.getMessage());
}
}A Consistent Error DTO
Return a uniform error shape so clients can parse failures predictably. Include a code, a human message, and optionally a timestamp and field details.
public record ApiError(
String code,
String message,
Instant timestamp) {
public ApiError(String code, String message) {
this(code, message, Instant.now());
}
}Handling Validation Errors
Catch MethodArgumentNotValidException to convert Bean Validation failures into a clear, field-by-field response instead of Spring’s default body.
@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
Map<String, String> errors = new HashMap<>();
ex.getBindingResult().getFieldErrors()
.forEach(e -> errors.put(e.getField(), e.getDefaultMessage()));
return errors;
}A Catch-All Handler
Add a handler for Exception as a safety net, returning 500 with a generic message. Crucially, log the real exception but never leak stack traces to clients.
@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ApiError handleUnexpected(Exception ex) {
log.error("Unhandled error", ex);
return new ApiError("INTERNAL_ERROR", "Something went wrong");
}Handler Selection Order
Spring picks the handler whose exception type most closely matches the thrown exception. A handler for OrderNotFoundException beats one for its superclass, so specific handlers take priority.
Scoping the Advice
You can narrow a @ControllerAdvice to specific packages, annotations, or controller types, allowing different error policies for, say, public vs internal APIs.
@RestControllerAdvice(basePackages = "com.example.api.publicapi")
public class PublicApiExceptionHandler { }Accessing the Request
Handler methods can accept extra parameters like WebRequest or HttpServletRequest to enrich responses with the path or a correlation id.
@ExceptionHandler(ResourceNotFoundException.class)
public ApiError notFound(ResourceNotFoundException ex, HttpServletRequest req) {
return new ApiError("NOT_FOUND", ex.getMessage() + " at " + req.getRequestURI());
}Security: Do Not Over-Share
Error responses are a common information-leak vector. Return enough for clients to act, but never expose internal class names, SQL, or stack traces. Log details server-side instead.
Quick Check
Test your understanding of centralized handling.
Recap
Centralize error handling.
@ExceptionHandlermaps exceptions to responses@ControllerAdviceapplies handlers across all controllers- Return a consistent error DTO
- Handle validation, domain, and catch-all cases
- Most specific handler wins; never leak internals to clients
よくある質問
「@ControllerAdviceと@ExceptionHandler」レッスンは無料ですか？
はい。「@ControllerAdviceと@ExceptionHandler」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Spring Boot 4 Microservices & REST APIsコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Spring Boot 4 Microservices & REST APIsコースには全4レッスンが含まれています。
「@ControllerAdviceと@ExceptionHandler」で何を学びますか？
例外をグローバルに処理します ブラウザで直接実行するハンズオンコードでSpring Boot 4 Microservices & REST APIsを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Spring Boot 4 Microservices & REST APIsを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのSpring Boot 4 Microservices & REST APIsは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン3/4です。
「@ControllerAdviceと@ExceptionHandler」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このSpring Boot 4 Microservices & REST APIsレッスンでコードを書いて実行できますか？
はい。すべてのSpring Boot 4 Microservices & REST APIsレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- @ValidによるBean Validation
- カスタムバリデーター
- @ControllerAdviceと@ExceptionHandler
- Problem Details（RFC 7807）