Controller Advice

Tratamento Global de Excecoes (@ControllerAdvice) — Addon Studio 2.0

@ControllerAdvice centraliza tratamento de excecoes de todos @Controller. Excecao capturada = rollback automatico da transacao ativa.

---

1. Anatomia

import br.com.sankhya.studio.web.ControllerAdvice;
import br.com.sankhya.studio.web.ExceptionHandler;
import java.util.logging.Level;
import java.util.logging.Logger;

@ControllerAdvice
public class GlobalExceptionHandler {

    private static final Logger log = Logger.getLogger(GlobalExceptionHandler.class.getName());

    @ExceptionHandler({ObjectNotFoundException.class})
    public ErrorResponse handleNotFound(ObjectNotFoundException e) {
        log.log(Level.INFO, "Recurso nao encontrado: {0}", e.getMessage());
        return new ErrorResponse("NOT_FOUND", e.getMessage(), 404);
    }

    @ExceptionHandler({IllegalArgumentException.class, ValidationException.class})
    public ErrorResponse handleValidation(Exception e) {   // parametro mais generico — OK
        log.log(Level.WARNING, "Validacao falhou", e);
        return new ErrorResponse("BAD_REQUEST", e.getMessage(), 400);
    }
}

---

2. Regras criticas

Retorno NUNCA pode ser void

@ExceptionHandler deve retornar objeto ou primitivo — sera serializado para JSON via Gson. void causa erro de compilacao.

// PROIBIDO
@ExceptionHandler({MinhaException.class})
public void handle(MinhaException e) { ... }

// CORRETO
@ExceptionHandler({MinhaException.class})
public ErrorResponse handle(MinhaException e) {
    return new ErrorResponse(...);
}

Multiplas excecoes no mesmo handler

@ExceptionHandler aceita array de classes:

@ExceptionHandler({IOException.class, SQLException.class, TimeoutException.class})
public ErrorResponse handleInfra(Exception e) {
    return new ErrorResponse("INFRA_ERROR", "Falha temporaria.", 503);
}

Parametro pode ser superclasse das excecoes declaradas

Util quando varias excecoes compartilham tratamento:

@ExceptionHandler({IOException.class, SQLException.class})
public ErrorResponse handle(Exception e) {  // Exception = superclasse comum
    ...
}

Rollback automatico

Excecao capturada = transacao ativa revertida via setRollbackOnly(). Sem acao manual necessaria.

NAO usar @ExceptionHandler({Exception.class})

Captura tudo (inclusive filhas), bloqueando handlers especificos. Sem ordem garantida entre @ControllerAdvice diferentes — handler generico de outra classe pode "roubar" excecao de handler especifico.

// PROIBIDO
@ExceptionHandler({Exception.class})
public ErrorResponse handleAll(Exception e) { ... }

// CORRETO — declarar excecoes especificas
@ExceptionHandler({MinhaException.class, OutraException.class})
public ErrorResponse handle(Exception e) { ... }

Sem ordem entre @ControllerAdvice distintos

Se duas classes @ControllerAdvice tratam a mesma excecao, framework escolhe qualquer uma sem ordem definida.

Regra: uma excecao = exatamente um handler em todo o projeto.

Metodos sem @ExceptionHandler sao silenciosamente ignorados

@ControllerAdvice
public class GlobalExceptionHandler {

    // IGNORADO — nao tem @ExceptionHandler
    public ErrorResponse handle(MinhaException e) { ... }
}

---

3. DTO de erro

Estrutura fica a criterio do projeto. Tipos diferentes de excecao podem retornar DTOs diferentes (NotFoundResponse, ValidationErrorResponse, etc.). Padrao comum:

import lombok.AllArgsConstructor;
import lombok.Data;

@Data
@AllArgsConstructor
public class ErrorResponse {
    private String code;
    private String message;
    private int status;
    private long timestamp;

    public ErrorResponse(String code, String message, int status) {
        this(code, message, status, System.currentTimeMillis());
    }
}

> Nunca incluir e.getStackTrace() ou e.toString() no DTO. Stack trace fica no log; mensagem ao cliente e amigavel.

---

4. Niveis de log sugeridos

| Excecao | Level | |:------------------------------|:----------| | EntityNotFoundException | INFO | | ObjectNotFoundException | INFO | | IllegalArgumentException | WARNING | | DomainValidationException | WARNING | | ValidationException | WARNING | | IntegrationImportException | WARNING | | IntegrationExportException | WARNING | | IntegrationApiException | WARNING | | IntegrationNetworkException | WARNING | | JapeSessionInterruptedError | SEVERE | | IOException / SQLException| SEVERE |

---

5. Anti-Patterns (PROIBIDO)

| Anti-Pattern | Correcao | |:----------------------------------------------------------|:----------------------------------------------------| | Handler retornando void | Retornar objeto/primitivo | | @ExceptionHandler({Exception.class}) como pega-tudo | Declarar excecoes especificas | | Duplicar handler da mesma excecao em classes diferentes | Uma excecao = um handler | | Metodo em @ControllerAdvice sem @ExceptionHandler | Adicionar a anotacao ou remover o metodo | | @ExceptionHandler({}) (array vazio) | Declarar ao menos uma classe | | Expor stack trace no DTO de resposta | Log no servidor; mensagem amigavel ao cliente | | Esquecer de logar a excecao | Sempre logar com Level adequado | | try/catch em controller para excecao de negocio | Deixar propagar — @ControllerAdvice trata |

---

6. Checklist: Novo @ControllerAdvice

1. [ ] Verificar que projeto nao tem outro handler para as mesmas excecoes.
2. [ ] Anotar classe com @ControllerAdvice.
3. [ ] Cada metodo handler com @ExceptionHandler({Excecao.class}) — array explicito.
4. [ ] Tipo de retorno e objeto/primitivo — nunca void.
5. [ ] Logger (java.util.logging) com Level adequado em todos os handlers.
6. [ ] DTO de resposta nao expoe stack trace nem dados sensiveis.
7. [ ] Nao declarar @ExceptionHandler({Exception.class}).
8. [ ] Confirmar que excecoes lancadas pela camada de servico estao mapeadas.

Skills relacionadas

• controller — endpoint REST que dispara as exceções tratadas; controllers devem deixar exceção propagar até o advice
• test — cobertura de cenários de erro

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: snk-devcenter
• Source: snk-devcenter/addon-studio
• License: MIT

Install and usage instructions live in the source repository linked above.