0Pricing
Spring Boot 4 Complete Guide · Pelajaran

Penanganan Pengecualian Global dengan @ControllerAdvice

Pusatkan penerjemahan pengecualian menjadi respons HTTP yang rapi menggunakan @ExceptionHandler dan @ControllerAdvice.

Penanganan Pengecualian Global dengan @ControllerAdvice adalah pelajaran Spring Boot 4 Complete Guide gratis di CoddyKit. Ini adalah pelajaran 3 dari 4. Kamu bisa membaca pelajaran lengkapnya di bawah secara gratis — lalu praktikkan langsung di browser dengan editor kode bawaan dan tutor AI 24/7. Ini adalah bagian dari jalur belajar Spring Boot 4 Complete Guide, dan progresmu tersinkronisasi di web dan aplikasi CoddyKit. Kursus Spring Boot 4 Complete Guide mencakup 4 pelajaran total.

Bagian dari pelajaran ini belum diterjemahkan dan ditampilkan dalam bahasa Inggris.

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.

Pertanyaan yang Sering Diajukan

Apakah pelajaran “Penanganan Pengecualian Global dengan @ControllerAdvice” gratis?

Ya — teks lengkap “Penanganan Pengecualian Global dengan @ControllerAdvice” gratis dibaca di sini di web. Untuk praktiknya secara interaktif (editor kode bawaan dan tutor AI 24/7) dan buka sisa kursus Spring Boot 4 Complete Guide, upgrade ke CoddyKit PRO. Kursus Spring Boot 4 Complete Guide mencakup 4 pelajaran total.

Apa yang akan aku pelajari di “Penanganan Pengecualian Global dengan @ControllerAdvice”?

Pusatkan penerjemahan pengecualian menjadi respons HTTP yang rapi menggunakan @ExceptionHandler dan @ControllerAdvice. Kamu berlatih Spring Boot 4 Complete Guide dengan kode praktik yang langsung kamu jalankan di browser, dan tutor AI 24/7 menjawab pertanyaanmu saat kamu mengerjakan pelajaran ini.

Apakah aku perlu pengalaman untuk memulai Spring Boot 4 Complete Guide?

Tidak diperlukan pengalaman sebelumnya. Spring Boot 4 Complete Guide di CoddyKit dirancang untuk pemula hingga pelajar tingkat lanjut, jadi kamu bisa memulai di sini atau dari awal dan belajar sesuai kecepatan kamu sendiri. Ini adalah pelajaran 3 dari 4.

Berapa lama pelajaran “Penanganan Pengecualian Global dengan @ControllerAdvice” memakan waktu?

Sebagian besar pelajaran CoddyKit memakan waktu sekitar 5–10 menit. Setiap pelajaran ringkas dan interaktif, jadi kamu membuat kemajuan stabil dan melanjutkan dari tempat kamu tinggalkan di web dan aplikasi.

Bisakah aku menulis dan menjalankan kode dalam pelajaran Spring Boot 4 Complete Guide ini?

Ya. Setiap pelajaran Spring Boot 4 Complete Guide menyertakan editor kode bawaan, jadi kamu menulis dan menjalankan kode nyata langsung di browser dan mendapatkan umpan balik AI instan — tidak diperlukan penyiapan lokal.

Semua pelajaran dalam kursus ini

  1. Kendala Validasi Bean dan Grup Kendala
  2. Membangun Anotasi Kendala Kustom
  3. Penanganan Pengecualian Global dengan @ControllerAdvice
  4. Respons Detail Masalah RFC 7807
← Kembali ke Spring Boot 4 Complete Guide