소프트웨어 시스템에서 예기치 않은 문제가 발생할 수 있습니다. 아무리 완벽하게 설계된 애플리케이션이라도 예외적인 상황에 직면할 수 있으며, 따라서 모든 애플리케이션은 이러한 오류에 대처하기 위한 체계를 갖추고 있어야 합니다.
스프링 부트는 오류 처리 기능을 자동화하여 기본적인 ‘화이트라벨’ 오류 페이지를 제공합니다. 하지만 개발자들은 이러한 기본 페이지를 자신만의 맞춤형 오류 페이지로 대체하는 경향이 있습니다. 이 글에서는 스프링 부트 애플리케이션에서 오류 페이지를 개별적으로 설정하는 방법에 대해 알아보겠습니다.
스프링 부트의 기본 오류 페이지
스프링 부트 애플리케이션에서 오류가 발생하면 시스템은 ‘/error’ URL을 통해 오류를 처리합니다. 이 주소에 해당하는 뷰가 없을 경우, 스프링 부트는 화이트라벨 오류 페이지를 표시합니다.
화이트라벨 오류 페이지에는 오류 발생 시각과 해당 시간대가 표시됩니다. 또한 오류의 종류와 관련 코드가 명시됩니다. 위의 예시에서는 404 오류(페이지를 찾을 수 없음)가 발생했음을 보여줍니다. 이는 샘플 애플리케이션에 ‘/products’ URL에 대한 매핑이 정의되지 않았기 때문입니다.
화이트라벨 오류 페이지에 표시되는 정보 대부분은 특정 오류 속성에서 비롯됩니다. 스프링 부트 오류 뷰는 다음과 같은 오류 속성에 접근할 수 있습니다:
- error: 오류의 원인이 되는 정보입니다.
- timestamp: 오류가 발생한 정확한 시간입니다.
- status: HTTP 오류 상태 코드입니다.
- exception: 예외 발생 시 최상위 예외의 클래스 이름입니다.
- message: 예외 발생 시 예외 메시지입니다.
- errors: BindingResult 예외와 관련된 정보입니다.
- trace: 예외 스택 추적 정보입니다.
- path: 오류가 발생한 URL 경로입니다.
Thymeleaf를 이용한 사용자 정의 오류 페이지 생성
스프링 부트 애플리케이션에서는 ‘error’라는 이름의 템플릿 파일을 오류 페이지로 사용합니다. 이 파일의 확장자는 사용하는 템플릿 엔진에 따라 다릅니다. 예를 들어, JSP(Java Server Pages)를 사용한다면 파일 이름은 ‘error.jsp’가 됩니다.
이 글의 예시에서는 Thymeleaf 템플릿 엔진을 사용하므로 템플릿 이름은 ‘error.html’이 됩니다. 이 오류 템플릿 파일은 다른 템플릿 파일들과 마찬가지로 리소스 디렉토리 하위의 템플릿 폴더에 위치해야 합니다.
error.html 파일 내용
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>오류 발생</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>문제가 발생했습니다!</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>요청하신 페이지에서 문제가 발생했습니다.
(<span th:text="${path}"></span>)</p>
<p th:text="${'상태 코드는 ' + status + '이며, 이는 페이지가 ' + error + '되었음을 의미합니다.'}"></p>
<p th:text="${'추가 정보: ' + message + '.'}"></p>
<a class="btn" href="https://wilku.top/home">홈으로 돌아가기</a>
</div>
</body>
</html>
사용자 정의 오류 페이지는 몇 가지 중요한 역할을 합니다. 우선 오류가 발생했다는 사실을 사용자에게 알립니다. 다음으로, 오류를 유발한 HTTP 요청을 사용자에게 보여줍니다. 또한 오류와 관련된 상태 코드 정보를 제공하며, 사용자가 상태 코드에 익숙하지 않은 경우, 오류 속성을 통해 코드의 의미를 설명합니다.
텍스트의 마지막 부분은 예외가 발생했을 때 사용자에게 메시지를 표시합니다. 페이지 하단의 링크는 사용자를 홈 페이지로 이동시키는 역할을 합니다. ‘error.html’ 파일은 CSS 스타일 시트와 두 개의 이미지를 활용하여 다음과 같은 사용자 인터페이스를 생성합니다.
사용자 친화적인 오류 페이지 디자인
오류 페이지의 주된 목적은 사용자에게 오류 발생 사실을 알리는 것입니다. 하지만 이 오류 페이지 또한 애플리케이션의 일부이므로 사용자 친화적으로 설계하는 것이 중요합니다.
오류 정보를 최대한 간단하고 명확하게 전달하기 위해 오류 속성을 활용해야 합니다. 사용자에게 불필요한 세부 정보를 제공할 수 있는 ‘trace’ 속성 대신 ‘path’ 속성을 사용하는 것이 한 예입니다.
애플리케이션 내부 작동에 대한 과도한 정보를 일반 사용자에게 제공하는 것은 애플리케이션 보안을 위태롭게 할 수 있으므로 피해야 합니다.