Capítulo 18 - O Protetor de Gotham

🚀 Capítulo 18: O Protetor de Gotham (Tema: Batman)

NOTE

Este capítulo utiliza a temática de Batman para explicar o tratamento global de erros com @ControllerAdvice no Spring Boot. Aprenda a centralizar a captura de falhas da sua API!

---

1. 🎯 Objetivo da Aula

Compreender como centralizar o tratamento de exceções da sua API usando a anotação @ControllerAdvice, evitando a repetição de blocos try-catch em todas as rotas e padronizando as mensagens de erro.

2. 🏢 O Cenário Prático (Seu Desafio)

Na sombria cidade de Gotham, os crimes acontecem em vários becos, ruas e bancos diferentes. Em vez de colocar um policial fixo em cada esquina esperando o crime acontecer (o que gastaria muito recurso), a polícia acende o Bat-Sinal no céu! O herói Batman fica em um ponto central (a Batcaverna), escuta o chamado e vai resolver o problema, não importa onde o crime tenha acontecido.

No capítulo $07$, nós aprendemos a usar o try-catch para capturar erros. Mas imagine que a sua API tenha $50$ rotas diferentes. Você teria que escrever $50$ blocos try-catch repetidos! Uma trabalheira digna de um capanga do Coringa!

• Para resolver isso, nós usamos o Batman do Spring: a anotação @ControllerAdvice!
• Ela cria uma classe central que fica “vigiando” todas as rotas do sistema. Se qualquer erro acontecer em qualquer rota, o @ControllerAdvice captura o erro e devolve uma resposta padrão e bonita para o usuário. Seu desafio é acender o Bat-Sinal!

---

🧠 Fundamentos: A Teoria Traduzida

🦇 1. O que é @ControllerAdvice?

É uma anotação que diz ao Spring: “Esta classe vai cuidar dos erros de todos os Controllers do sistema”.

🚨 2. A Anotação @ExceptionHandler:

Dentro dessa classe central, nós criamos métodos para cuidar de erros específicos e colocamos a anotação @ExceptionHandler dizendo qual erro queremos capturar.

@ControllerAdvice
public class GerenciadorDeErros {
 
    // Se acontecer um erro de validação (Bean Validation), o Batman captura aqui!
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<String> tratarErroDeValidacao() {
        return ResponseEntity.status(400).body("Dados inválidos! Por favor, corrija.");
    }
}

---

4. 📖 Exemplo Guiado: O Objeto de Erro Padrão

Em APIs profissionais, quando dá erro, nós não enviamos apenas um texto. Nós enviamos um objeto JSON estruturado (um DTO de erro!):

public class ErroPadraoDTO {
    private String mensagem;
    private int status;
    private Long timestamp;
    
    // Construtor e Getters...
}

Assim, o aplicativo do usuário sempre receberá o erro no mesmo formato, facilitando a vida do desenvolvedor frontend!

---

5. 🛠️ Prática Obrigatória 1: Centralizando o Erro

Com base no texto:

1. Qual é a principal vantagem de usar a anotação @ControllerAdvice em um projeto Spring Boot em vez de colocar blocos try-catch dentro de cada método de rota?

6. 🛠️ Prática Obrigatória 2: O Capturador Específico

1. Qual é a anotação que usamos em cima de um método dentro da classe de @ControllerAdvice para dizer ao Spring qual tipo específico de exceção aquele método deve capturar?

---

7. 📤 Instruções de Entrega (GitHub Desktop + Microsoft Teams)

1. Faça o Commit: No GitHub Desktop, digite a mensagem (ex: Finaliza Capítulo 18 Java_Batman) e clique em Commit to main.
2. Envie para a Nuvem (Push): Clique em Push origin.

---

8. 📂 Estrutura de Pastas

spec_backend_com_java_e_springboot/
├── capitulos/
│   └── capitulo_18_batman.md

💡 Checkpoint de Lógica

Você pode criar um método genérico com @ExceptionHandler(Exception.class) para capturar qualquer erro desconhecido do sistema, funcionando como uma rede de segurança para a sua API nunca quebrar e mostrar aquela tela feia de erro do servidor!

10. 🔥 Desafio de Fixação

Pesquise como capturar a mensagem de erro específica que o Bean Validation gerou (aquela que colocamos dentro do parâmetro message="...") para enviar dentro do seu DTO de erro padrão.

🔑 Gabarito de Código/Fórmulas

Gabarito da Prática 1:

1. A principal vantagem é a não repetição de código (DRY - Don’t Repeat Yourself) e a padronização das respostas. Você escreve o tratamento de erro apenas uma vez em um lugar central, e ele passa a valer para todo o projeto, deixando os seus Controllers limpos e focados apenas na lógica da rota! Gabarito da Prática 2:
2. É a anotação @ExceptionHandler.

---

← Capitulo Anterior | Proximo Capitulo →