웹 애플리케이션을 개발하다 보면 사용자가 특정 요청을 처리하지 못했을 때, 기본적으로 제공되는 오류 페이지가 아닌 **커스텀 오류 페이지(Custom Error Page)**를 설정하는 경우가 많습니다. 커스텀 오류 페이지는 사용자 경험을 개선하고, 브랜드 이미지 및 애플리케이션의 신뢰도를 높이는 데 기여합니다.
이번 글에서는 스프링 부트 3(Sprint Boot 3)를 사용하여 Custom Error Page를 구현하는 방법을 단계별로 살펴보겠습니다.
1. Custom Error Page의 필요성
스프링 부트는 오류 발생 시 기본 오류 페이지(Whitelabel Error Page)를 제공합니다. 하지만 이 페이지는 사용자 친화적이지 않고, 애플리케이션의 내부 정보를 노출할 위험이 있습니다.
Custom Error Page를 생성하면 다음과 같은 장점이 있습니다:
- 브랜드 아이덴티티 강화: 오류 페이지에 로고나 디자인 요소를 추가해 애플리케이션의 정체성을 강조할 수 있습니다.
- 사용자 안내 강화: 친근하고 이해하기 쉬운 메시지로 사용자가 다음에 해야 할 작업을 안내할 수 있습니다.
- 보안 강화: 오류 발생 시 내부 정보가 노출되지 않도록 보호할 수 있습니다.
2. Custom Error Page 생성 방법
(1) HTML 기반 오류 페이지 설정
스프링 부트는 기본적으로 src/main/resources/static 또는 src/main/resources/templates 디렉토리에 HTML 파일을 배치해 오류 페이지를 설정할 수 있습니다.
404.html 예제
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>페이지를 찾을 수 없습니다</title>
<style>
body {
font-family: Arial, sans-serif;
text-align: center;
margin-top: 50px;
}
h1 {
color: #FF0000;
}
p {
font-size: 18px;
}
a {
color: #007BFF;
text-decoration: none;
}
</style>
</head>
<body>
<h1>404 오류 - 페이지를 찾을 수 없습니다</h1>
<p>요청하신 페이지가 존재하지 않습니다. <a href="/">홈으로 돌아가기</a></p>
</body>
</html>
이 HTML 파일을 src/main/resources/templates에 저장하면 404 오류 발생 시 자동으로 적용됩니다.
(2) JSON 기반 오류 메시지 설정
API 서버에서는 HTML보다는 JSON 형식으로 오류 메시지를 제공하는 경우가 많습니다. 이를 구현하려면 ErrorController를 커스터마이징해야 합니다.
CustomErrorController.java
package com.example.demo.controller;
import org.springframework.boot.web.error.ErrorAttributeOptions;
import org.springframework.boot.web.servlet.error.ErrorAttributes;
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.context.request.WebRequest;
import java.util.Map;
@Controller
public class CustomErrorController implements ErrorController {
private final ErrorAttributes errorAttributes;
public CustomErrorController(ErrorAttributes errorAttributes) {
this.errorAttributes = errorAttributes;
}
public ResponseEntity<Map<String, Object>> handleError(WebRequest webRequest) {
Map<String, Object> attributes = errorAttributes.getErrorAttributes(webRequest, ErrorAttributeOptions.defaults());
HttpStatus status = HttpStatus.valueOf((int) attributes.get("status"));
return new ResponseEntity<>(attributes, status);
}
public String getErrorPath() {
return "/error";
}
}
이 코드는 API 요청에서 발생한 오류를 JSON 형식으로 반환합니다. 예를 들어, 404 오류가 발생하면 다음과 같은 응답을 받을 수 있습니다:
{
"timestamp": "2024-12-05T12:34:56.789+09:00",
"status": 404,
"error": "Not Found",
"message": "해당 URL을 찾을 수 없습니다.",
"path": "/invalid-path"
}
(3) 특정 오류 코드별 커스텀 페이지 설정
스프링 부트에서는 특정 HTTP 상태 코드에 따라 다른 오류 페이지를 설정할 수 있습니다. 이를 위해 ErrorViewResolver를 사용할 수 있습니다.
CustomErrorViewResolver.java
package com.example.demo.config;
import org.springframework.boot.web.servlet.error.ErrorViewResolver;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.ModelAndView;
import javax.servlet.http.HttpServletRequest;
import java.util.Map;
@Component
public class CustomErrorViewResolver implements ErrorViewResolver {
@Override
public ModelAndView resolveErrorView(HttpServletRequest request, HttpStatus status, Map<String, Object> model) {
if (status == HttpStatus.NOT_FOUND) {
return new ModelAndView("404");
} else if (status == HttpStatus.INTERNAL_SERVER_ERROR) {
return new ModelAndView("500");
}
return new ModelAndView("error");
}
}
여기서 404.html과 500.html은 오류별로 제공할 HTML 파일입니다.
3. Custom Error Page 구현 예제
예제 1: 404 페이지
404 오류가 발생했을 때 사용자에게 친근한 안내 메시지를 표시합니다.
- HTML 예제: 위에서 설명한 404.html 파일
- 적용 경로: /invalid-path
예제 2: API의 JSON 오류 응답
사용자가 /api/invalid 경로에 접근했을 때, JSON 형식으로 다음과 같은 오류 메시지가 반환됩니다:
{
"status": 404,
"message": "해당 API를 찾을 수 없습니다.",
"path": "/api/invalid"
}
예제 3: 500 페이지
서버 오류가 발생했을 때 500.html을 보여줍니다.
- HTML 예제:
<h1>서버 오류</h1>
<p>현재 서버에 문제가 발생했습니다. 잠시 후 다시 시도해 주세요.</p>
4. 결론
Custom Error Page는 사용자 경험을 향상시키고 애플리케이션의 품질을 높이는 데 중요한 요소입니다. 스프링 부트 3를 활용하면 간단한 설정으로 HTML 기반 페이지부터 JSON 응답까지 다양한 형식으로 커스터마이징할 수 있습니다.
지금 바로 커스텀 오류 페이지를 구현해 애플리케이션의 전문성을 한 단계 업그레이드하세요! 🚀
'스프링 부트3' 카테고리의 다른 글
| 스프링 부트 3에서 데이터 암호화 처리 (0) | 2024.12.11 |
|---|---|
| 스프링 부트 3에서 ApplicationRunner와 CommandLineRunner (0) | 2024.12.11 |
| 스프링 부트 3에서 다국어 지원 구현 (0) | 2024.12.11 |
| HTTP 클라이언트: WebClient 사용법 (0) | 2024.12.11 |
| 스프링 부트 3에서 Pageable과 Sort 사용하기 (0) | 2024.12.11 |