0Pricing
Spring Boot 4 Complete Guide · Ders

@ControllerAdvice ile Genel Hata Yönetimi

@ExceptionHandler ve @ControllerAdvice kullanarak istisnaların temiz HTTP yanıtlarına dönüştürülmesini merkezileştirin.

@ControllerAdvice ile Genel Hata Yönetimi, CoddyKit'te ücretsiz bir Spring Boot 4 Complete Guide dersidir. Bu, 4 dersinin 3. dersidir. Aşağıdan dersin tamamını ücretsiz okuyabilir, sonra tarayıcıda yerleşik kod editörü ve 7/24 yapay zeka koçu ile uygulamalı olarak pratik yapabilirsin. Bu, Spring Boot 4 Complete Guide öğrenme yolunun bir parçasıdır ve ilerlemeniz web ve CoddyKit uygulaması arasında senkronize olur. Spring Boot 4 Complete Guide kursu toplamda 4 dersten oluşur.

Bu dersin bazı bölümleri henüz çevrilmemiş olup İngilizce olarak gösterilmektedir.

Why Centralize Exception Handling?

When something goes wrong in a Spring Boot REST API, the client should receive a clean, predictable HTTP response, not a raw stack trace.

Without a strategy, you end up scattering try/catch blocks across every controller method, repeating the same JSON-building logic over and over.

  • Inconsistent status codes for the same error type
  • Duplicated error-response shaping
  • Leaked internal details (stack traces, SQL) to clients

Global exception handling solves this by translating exceptions into HTTP responses in one place.

The @ExceptionHandler Building Block

The core annotation is @ExceptionHandler. It marks a method that handles a specific exception type thrown during request processing.

Placed inside a controller, it only catches exceptions thrown by that controller's handler methods.

The method's parameter declares which exception it handles, and its return value becomes the HTTP response.

@RestController
public class ProductController {

    @GetMapping("/products/{id}")
    public Product getProduct(@PathVariable Long id) {
        throw new ProductNotFoundException(id);
    }

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

From Local to Global with @ControllerAdvice

A local @ExceptionHandler only covers one controller. To share handlers across the whole application, move them into a class annotated with @ControllerAdvice.

@ControllerAdvice is a specialization of @Component. Spring registers its @ExceptionHandler methods globally, so any controller that throws a matching exception is handled here.

For REST APIs, prefer @RestControllerAdvice, which combines @ControllerAdvice with @ResponseBody so return values are serialized to JSON automatically.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<String> handleNotFound(ProductNotFoundException ex) {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(ex.getMessage());
    }
}

A Consistent Error Response Body

Returning a raw string is rarely enough. Clients want a structured, predictable JSON body they can parse.

Define a small error response record that every handler returns. This is plain Java, no framework needed, so it is fully standalone.

Spring serializes this record to JSON when returned from a @RestControllerAdvice method.

import java.time.Instant;

public record ApiError(
        Instant timestamp,
        int status,
        String error,
        String message,
        String path) {
}

public class Demo {
    public static void main(String[] args) {
        ApiError err = new ApiError(
                Instant.parse("2026-01-01T10:15:30Z"),
                404,
                "Not Found",
                "Product 42 not found",
                "/products/42");
        System.out.println(err);
    }
}

Returning Structured Errors with ResponseEntity

Now combine the ApiError record with your global handler. Build a ResponseEntity that carries both the correct status code and the structured body.

Use the injected HttpServletRequest to capture the request path, which is helpful for debugging on the client side.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ProductNotFoundException ex, HttpServletRequest request) {

        ApiError error = new ApiError(
                Instant.now(),
                HttpStatus.NOT_FOUND.value(),
                HttpStatus.NOT_FOUND.getReasonPhrase(),
                ex.getMessage(),
                request.getRequestURI());

        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Mapping Status with @ResponseStatus

If a handler always returns the same status and you do not need custom headers, you can skip ResponseEntity entirely.

Annotate the handler method with @ResponseStatus(...) and return the body directly. Spring applies the status code for you.

This keeps simple handlers concise, but reach for ResponseEntity when you need dynamic status codes or headers.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError handleNotFound(ProductNotFoundException ex, HttpServletRequest req) {
        return new ApiError(Instant.now(), 404, "Not Found",
                ex.getMessage(), req.getRequestURI());
    }
}

Handling Validation Errors

When a @Valid request body fails Bean Validation, Spring throws MethodArgumentNotValidException. By default the JSON response is verbose and noisy.

Override it in your advice to return a clean map of field errors. Each FieldError carries the offending field name and the validation message.

@ExceptionHandler(MethodArgumentNotValidException.class)
@ResponseStatus(HttpStatus.BAD_REQUEST)
public Map<String, String> handleValidation(MethodArgumentNotValidException ex) {
    Map<String, String> errors = new HashMap<>();
    for (FieldError fieldError : ex.getBindingResult().getFieldErrors()) {
        errors.put(fieldError.getField(), fieldError.getDefaultMessage());
    }
    return errors;
}

One Handler for Many Exceptions

@ExceptionHandler accepts an array of exception classes, so a single method can handle several related types that map to the same status.

This avoids duplicate code when, say, several distinct "bad input" exceptions should all become 400 Bad Request.

@ExceptionHandler({
        IllegalArgumentException.class,
        IllegalStateException.class,
        ConstraintViolationException.class
})
@ResponseStatus(HttpStatus.BAD_REQUEST)
public ApiError handleBadRequest(RuntimeException ex, HttpServletRequest req) {
    return new ApiError(Instant.now(), 400, "Bad Request",
            ex.getMessage(), req.getRequestURI());
}

Exception Resolution Order

When an exception is thrown, Spring picks the most specific matching @ExceptionHandler.

  • An exact-type handler wins over a handler for its superclass.
  • Local handlers in the controller take precedence over global ones in @ControllerAdvice.
  • If two handlers are equally specific, Spring raises an ambiguity error at startup.

This ordering lets you provide a broad fallback while still overriding specific cases.

A Safe Catch-All Fallback

Always provide a last-resort handler for Exception.class. It catches anything you did not explicitly map and prevents internal details from leaking.

Return a generic 500 Internal Server Error with a safe message, and log the real exception server-side for investigation.

Never put the raw exception message or stack trace into the client response for unexpected errors.

@ExceptionHandler(Exception.class)
@ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR)
public ApiError handleAny(Exception ex, HttpServletRequest req) {
    log.error("Unhandled exception at {}", req.getRequestURI(), ex);
    return new ApiError(Instant.now(), 500, "Internal Server Error",
            "An unexpected error occurred", req.getRequestURI());
}

Scoping and Extending the Framework Base

You can scope an advice to a subset of controllers using attributes like @RestControllerAdvice(basePackages = "com.shop.api") or assignableTypes = {...}. Unscoped advice applies everywhere.

For full control over Spring MVC's built-in exceptions (missing parameters, unreadable bodies, unsupported media types), extend ResponseEntityExceptionHandler and override its protected methods. It already declares handlers for the standard MVC exceptions.

@RestControllerAdvice
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

    @ExceptionHandler(ProductNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ProductNotFoundException ex, HttpServletRequest req) {
        ApiError error = new ApiError(Instant.now(), 404, "Not Found",
                ex.getMessage(), req.getRequestURI());
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
    }
}

Quick Check

You have a REST API. You want validation errors and not-found errors to produce consistent JSON bodies and correct status codes across every controller, in one place. What is the idiomatic Spring Boot approach?

Recap

You learned how to centralize exception handling in Spring Boot:

  • @ExceptionHandler maps an exception type to an HTTP response; alone it is controller-local.
  • @RestControllerAdvice registers handlers globally and serializes return values to JSON.
  • Return a consistent error record (status, message, path, timestamp) for predictable clients.
  • Use ResponseEntity for dynamic status/headers, or @ResponseStatus for fixed ones.
  • Handle MethodArgumentNotValidException for clean validation errors, group related exceptions, and always add an Exception.class catch-all that hides internals.

The result is consistent, secure, and maintainable error responses across your whole API.

Sıkça Sorulan Sorular

“@ControllerAdvice ile Genel Hata Yönetimi” dersi ücretsiz mi?

Evet — “@ControllerAdvice ile Genel Hata Yönetimi” dersin tüm metni burada web'de ücretsiz olarak okunabilir. Etkileşimli olarak pratik yapmak (yerleşik kod editörü ve 7/24 yapay zeka koçu) ve Spring Boot 4 Complete Guide kursunun geri kalanını açmak için CoddyKit PRO'ya yükselt. Spring Boot 4 Complete Guide kursu toplamda 4 dersten oluşur.

“@ControllerAdvice ile Genel Hata Yönetimi” dersinde ne öğreneceğim?

@ExceptionHandler ve @ControllerAdvice kullanarak istisnaların temiz HTTP yanıtlarına dönüştürülmesini merkezileştirin. Spring Boot 4 Complete Guide ile uygulamalı kodu tarayıcıda doğrudan çalıştırarak pratik yaparsın ve 7/24 yapay zeka koçu dersi çalışırken sorularını yanıtlar.

Spring Boot 4 Complete Guide öğrenmeye başlamak için deneyim gerekli mi?

Önceden deneyim gerekmez. CoddyKit'te Spring Boot 4 Complete Guide, başlangıçtan ileri seviyeye kadar yapılandırıldığı için buradan başlayabilir veya başından başlayıp kendi hızında ilerleme yapabilirsin. Bu, 4 dersinin 3. dersidir.

“@ControllerAdvice ile Genel Hata Yönetimi” dersi ne kadar sürer?

Çoğu CoddyKit dersi yaklaşık 5–10 dakika sürer. Her biri kısa ve etkileşimli olduğu için sabit ilerleme yaparsın ve web ile uygulama arasında tam olarak bıraktığın yerden devam edebilirsin.

Bu Spring Boot 4 Complete Guide dersinde kod yazıp çalıştırabilir miyim?

Evet. Her Spring Boot 4 Complete Guide dersi yerleşik bir kod editörü içerir, bu sayede tarayıcıda gerçek kod yazıp çalıştırabilir ve anlık yapay zeka geri bildirimi alırsın — yerel kurulum gerekli değildir.

Bu kursun tüm dersleri

  1. Bean Validation Kısıtlamaları ve Kısıtlama Grupları
  2. Özel Kısıtlama Açıklamaları Oluşturma
  3. @ControllerAdvice ile Genel Hata Yönetimi
  4. RFC 7807 ProblemDetail Yanıtları
← Spring Boot 4 Complete Guide Sayfasına Dön