Exceptions sem drama: como tratar erros em uma API Spring

Leia. Curta. Comente. Compartilhe.

...

"Entenda de forma simples como Exceptions e HTTP Status ajudam sua API a lidar com erros e devolver respostas mais claras para quem está do outro lado."

...

Sua aplicação está funcionando perfeitamente.

Até alguém fazer algo que você não esperava.

Buscar um cliente que não existe, enviar um campo errado ou tentar acessar alguma coisa sem permissão.

E aí vem ela:

Exception.

Mas o problema não é sua API ter erros. Erros fazem parte de qualquer aplicação.

O problema é quando ela não sabe explicar o que aconteceu.

Imagine pedir uma pizza

Você abre o aplicativo e pede uma pizza de calabresa.

Só que acabou a calabresa.

Existem duas formas do restaurante responder.

Resposta 1:

ERRO INTERNO. CÓDIGO 584739.

Você provavelmente ficaria pensando:

"Tá... mas eu fiz o quê?"

Agora imagine:

Resposta 2:

Calabresa indisponível. Escolha outro sabor.

O problema continua existindo, mas agora você entende o que aconteceu e sabe o que fazer.

Uma API deveria seguir uma lógica parecida.

É aqui que entram as Exceptions

Imagine uma API que busca clientes pelo ID:

GET /clientes/123

Se o cliente 123 existe, perfeito.

Mas e se não existir?

A aplicação precisa perceber essa situação e decidir como responder.

Em vez de devolver um erro enorme e incompreensível, podemos retornar algo como:

{
"status": 404,
"mensagem": "Cliente não encontrado"
}

Muito melhor.

A Exception identifica que algo deu errado. O tratamento decide como nossa aplicação vai responder a esse problema.

E aqueles números 200, 404, 500...?

Esses números são os HTTP Status.

Eles ajudam quem está consumindo nossa API a entender rapidamente o resultado de uma requisição.

Alguns aparecem bastante:

200 OK

Deu tudo certo.

400 Bad Request

A requisição chegou com algum problema.

401 Unauthorized

Você ainda precisa provar quem é.

403 Forbidden

Sabemos quem você é, mas você não pode entrar aqui.

404 Not Found

Aquilo que você procurou não foi encontrado.

500 Internal Server Error

Alguma coisa deu errado dentro da aplicação.

Dá até para pensar neles como respostas de uma festa:

200: Pode entrar!

401: Quem é você?

403: Você está na lista, mas não tem acesso ao camarote.

404: Essa festa nem é aqui.

500: A festa era aqui, mas alguém derrubou a mesa do DJ.

Não espalhe tratamento de erro pelo projeto inteiro

Imagine ter vários lugares fazendo isso:

try {
  // alguma coisa
} catch (Exception e) {
  // trata o erro
}

Depois outro.

E outro.

E mais outro.

Quando o projeto cresce, começa aquela caça ao tesouro para descobrir onde cada erro está sendo tratado.

No Spring, podemos centralizar esse trabalho utilizando recursos como:

@RestControllerAdvice

A ideia é ter um lugar responsável por transformar determinadas Exceptions em respostas mais organizadas.

Assim, em vez de cada Controller inventar sua própria forma de responder, conseguimos manter um padrão.

O código fica mais organizado e quem consome a API recebe respostas mais previsíveis.

3 coisas para lembrar quando sua API der erro

1. Não esconda o problema

Retornar 200 OK quando alguma coisa deu errado só para parecer que está tudo bem não ajuda ninguém.

O status precisa representar o que realmente aconteceu.

2. Dê uma mensagem que faça sentido

Compare:

"Erro inesperado XPTO_9283"

com:

"Cliente não encontrado."

Quem está consumindo sua API agradece.

3. Nem todo erro é 500

Esse é importante.

Cliente não encontrado? Talvez seja 404.

Dados enviados incorretamente? Pode ser 400.

Sem permissão? Pode ser 403.

O HTTP Status ajuda a contar o que aconteceu sem precisar escrever um livro na resposta.

Uma boa API também precisa saber errar

Nenhuma aplicação vai funcionar perfeitamente em todos os cenários.

Usuários vão enviar informações erradas, registros não vão existir, integrações podem falhar e situações inesperadas vão aparecer.

Por isso, tratar Exceptions não significa tentar criar uma aplicação que nunca tenha erros.

Significa criar uma aplicação que, quando algo der errado, consiga responder de uma forma clara e organizada.

No fim, sua API não precisa fingir que está tudo bem.

Ela só precisa saber dizer:

"Deu errado, e foi por isso."

E isso já ajuda bastante quem está do outro lado.

Qual HTTP Status mais confundiu você quando começou a trabalhar com APIs: 401, 403, 404 ou 500?

___________________________

Indicação de livro

Spring Start Here

Autor: Laurentiu Spilca

É uma boa leitura para quem está aprendendo Spring e quer entender melhor como as peças do framework se conectam, incluindo a construção de APIs e o tratamento das situações que aparecem pelo caminho.