Qualquer software, mesmo os mais bem construídos, está sujeito a apresentar falhas em algum momento. Sendo assim, é imprescindível que todos os aplicativos possuam mecanismos robustos para o tratamento de erros.
O Spring Boot, por padrão, oferece uma página de erro “Whitelabel” como parte de sua configuração automática para lidar com erros. No entanto, espera-se que os desenvolvedores personalizem essa página, criando uma versão própria que a substitua. Este artigo abordará como customizar a página de erro em suas aplicações Spring Boot.
A Página de Erro Whitelabel do Spring Boot
Quando um aplicativo Spring Boot encontra um erro, ele automaticamente direciona para a URL “/error”. Se não houver uma visualização configurada para esse endereço, a página de erro Whitelabel será exibida.
Essa página apresenta informações como a data e hora em que o erro ocorreu, junto com o fuso horário. Além disso, ela indica o tipo de erro e seu respectivo código. No exemplo, a página Whitelabel demonstra um erro 404 (página não encontrada), pois o aplicativo de exemplo não tem um mapeamento para a URL “/produtos”.
As informações exibidas na página de erro Whitelabel são extraídas de atributos de erro específicos. A visualização de erros do Spring Boot tem acesso aos seguintes atributos:
- error: a descrição do erro.
- timestamp: o instante exato em que o erro aconteceu.
- status: o código de status HTTP do erro.
- exception: o nome da classe da exceção raiz, caso o erro seja resultado de uma.
- message: a mensagem de exceção detalhada, caso o erro seja resultado de uma.
- errors: quaisquer resultados de uma exceção BindingResult, em casos específicos.
- trace: o rastreamento da pilha de exceções, se o erro decorrer de uma exceção.
- path: o caminho da URL onde o erro ocorreu.
Criando uma Página de Erro Personalizada com Thymeleaf
Em sua aplicação Spring Boot, você deve criar uma página de erro única, armazenada em um modelo nomeado “error”. A extensão deste modelo dependerá da tecnologia que você escolher para seus templates. Por exemplo, se você optar por usar Java Server Pages (JSP), o arquivo deverá ser nomeado error.jsp.
No entanto, o exemplo de aplicação neste artigo utiliza o motor de templates Thymeleaf. Portanto, o modelo foi nomeado error.html. Recomenda-se que você armazene seu modelo de erro na pasta de modelos, dentro do diretório de recursos, juntamente com todos os outros arquivos de template.
O Arquivo error.html
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title> Erro</title>
<link rel="stylesheet" th:href="https://wilku.top/how-to-create-custom-spring-boot-error-pages-with-thymeleaf/@{/css/style.css}"/>
</head>
<body th:style="'background: url(/images/background1.jpg)
no-repeat center center fixed;'">
<div class="container" >
<h1>Ocorreu um erro...</h1>
<img th:src="https://wilku.top/how-to-create-custom-spring-boot-error-pages-with-thymeleaf/@{/images/error-icon.png}"
width="100px" height="100px" />
<p>Parece haver um problema com a página que você solicitou
(<span th:text="${path}"></span>).</p>
<p th:text="${'O código de status é ' + status
+ ', o que significa que a página foi ' + error + '.'}"></p>
<p th:text="${'Mais detalhes: ' + message + '.'}"></p>
<a class="btn" href="https://wilku.top/home">Voltar para a página inicial</a>
</div>
</body>
</html>
Esta página de erro personalizada executa várias tarefas importantes. Primeiramente, ela informa ao usuário que um erro ocorreu. Em seguida, exibe a solicitação HTTP que causou o erro. Além disso, ela apresenta o código de status associado ao erro. Caso o usuário não esteja familiarizado com códigos de status, a página também explica o significado do código por meio do atributo “error”.
A última linha de texto mostra uma mensagem de exceção, caso ela tenha ocorrido. E finalmente, o link no final permite que o usuário retorne à página inicial. O arquivo error.html utiliza um arquivo CSS e duas imagens para gerar a seguinte visualização:
Mantenha sua Página de Erro Amigável
O principal propósito da página de erro é notificar o usuário sobre a ocorrência de um problema específico. No entanto, essa página ainda é parte da experiência do usuário com a aplicação. Portanto, é fundamental que ela também seja amigável e fácil de entender.
Isso implica escolher utilizar atributos de erro que comuniquem o problema de maneira clara e direta. Por exemplo, é preferível usar o atributo “path” em vez do atributo “trace”, que é muito mais complexo e contém detalhes que o usuário não precisa conhecer.
Ademais, é importante evitar expor informações detalhadas sobre o funcionamento interno da aplicação para usuários aleatórios, pois isso pode representar um risco para a segurança do sistema.