Spring Boot - 스프링 부트 Whitelabel 에러 처리 방법
- 프로그래밍/스프링
- 2021. 10. 26.
이번 글에서는 스프링 부트에서 제공하는 화이트라벨(Whitelabel) 대신 사용자가 정의한 오류 페이지를 사용하는 방법에 대해 이야기해볼까 합니다. 스프링 부트의 오류 처리 방법은 스프링에서 정의한 화이트라벨(Whitelabel)이 기본값으로 사용됩니다. 토이 프로젝트에서 사용하기는 문제가 없지만 멋진 웹 프로젝트를 만들기 위해서는 사용자 정의 에러 페이지를 쓰는 것이 좋습니다.
Spring Boot에서 정의하는 오류 처리 방법 - feat. Whitelabel
Spring Boot Features - Error Handling에서는 스프링 부트 오류 처리 방법에 대해 아래와 같이 정의합니다.
By default, Spring Boot provides an /error mapping that handles all errors in a sensible way, and it is registered as a “global” error page in the servlet container. For machine clients, it produces a JSON response with details of the error, the HTTP status, and the exception message. For browser clients, there is a “whitelabel” error view that renders the same data in HTML format (to customize it, add a View that resolves to error).
There are a number of server.error properties that can be set if you want to customize the default error handling behavior. See the “Server Properties” section of the Appendix.
To replace the default behavior completely, you can implement ErrorController and register a bean definition of that type or add a bean of type ErrorAttributes to use the existing mechanism but replace the contents.
기본적으로 스프링 부트는 모든 오류를 적절한 방법으로 처리하는 /error 매핑을 제공하며 서블릿 컨테이너에 "global" 오류 페이지로 등록됩니다. 클라이언트의 경우 오류, HTTP 상태 및 예외 메시지에 대한 세부 정보가 포함된 JSON 응답을 생성합니다. 브라우저 클라이언트의 경우 동일한 데이터를 HTML 형식으로 렌더링 하는 "whitelabel" 오류 보기가 있습니다. (사용자 정의를 하려면 error를 해결하는 resolves를 추가하세요).
기본 오류 처리 동작을 사용자 정의하려는 경우 설정할 수 있는 server.error 속성에는 여러 가지가 있습니다. 부록의 "서버 속성" 섹션을 참조하십시오.
기본 동작을 완전히 바꾸려면 ErrorController를 구현하고 해당 유형의 빈 정의를 등록하거나 ErrorAttributes 유형의 빈을 추가하여 기존 메커니즘을 사용하지만 내용을 바꿀 수 있습니다.
스프링 부트에서는 오류 처리에 대해 별다른 정의가 없다면 Whitelabel을 기본값으로 사용합니다. Whitelabel은 기본 오류 처리 페이지보다는 좋은 시안성을 가진 에러 처리 페이지를 보여줍니다.
하지만 앞서 이야기한 것처럼 멋진 웹 프로젝트를 만들기 위해서는 오류 처리 페이지로 whitelabel 대신 사용자 정의 오류 페이지를 만들고 사용하는 것이 좋습니다. 또한 전문가가 만든 웹 사이트는 상황에 따라 적합한 방법으로 오류를 처리할 수 있어야 하기 때문에 단순히 멋진 웹 사이트를 위해서가 아니라 좋은 웹 사이트를 만들기 위해서도 사용자 정의 오류 페이지를 사용하는 것이 좋습니다.
사용자 정의 오류 페이지 정의하고 사용하기
스프링 부트에서 사용자 정의 오류 페이지를 사용하는 방법에 대해 공식 문서는 아래와 같이 설명합니다. 기본적으로 제시하는 방법은 /error 폴더를 추가해 오류를 처리하는 static HTML 파일을 추가해 정의하는 것입니다. 이때 정의하는 HTML 파일의 이름은 HTTP 상태 코드(4xx, 5xx)를 따라야 합니다.
If you want to display a custom HTML error page for a given status code, you can add a file to an /error directory. Error pages can either be static HTML (that is, added under any of the static resource directories) or be built by using templates. The name of the file should be the exact status code or a series mask.
지정된 상태 코드에 대한 사용자 정의 HTML 오류 페이지를 정의하는 경우에 /error 디렉토리에 파일을 추가할 수 있습니다. 오류 페이지는 static HTML(즉, 정적 리소스 디렉토리 아래에 추가)이거나 템플릿을 사용하여 만들 수 있습니다. 파일 이름은 정확한 상태 코드 또는 series mask여야 합니다.
오류 처리 페이지 추가
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<title>오류 페이지</title>
</head>
<body>
문제가 발생했습니다.
</body>
</html>먼저 resources/public/error 폴더 구조를 정의한 후 4xx.html, 5xx.html 파일을 추가해주세요.
그림과 같이 4xx.html, 5xx.html 파일을 resources/public/error 폴더에 추가하면 400, 500번 대의 오류 발생 시 아래와 같은 화면을 확인할 수 있습니다. 오류 처리를 위해 별다른 처리를 하지 않고 오류 상태 코드와 동일한 이름을 가진 html 파일을 추가하는 것만으로도 사용자가 정의 한 오류 처리 페이지를 사용할 수 있습니다.
보다 구체적으로 오류 페이지를 사용하려면 4xx, 5xx 대신 HTTP 상태 코드로 html 파일을 정의하면 됩니다. 예를 들어 정확한 위치를 찾을 수 없거나 유효하지 않은 URL을 입력한 경우 발생하는 404 오류는 resources/public/error 폴더에 404.html 파일을 추가하면 됩니다. 이에 대한 내용은 아래와 같이 공식 문서에 정의되어 있습니다.
thymeleaf, FreeMarker와 같은 템플린 엔진을 사용하는 경우에는 public 폴더 대신 templates 폴더를 사용하면 됩니다.
public 폴더와 templates 폴더 두 개의 폴더에 error이 정의된 경우에는 viewResolver에 정의된 우선순위에 따라 표출되는 파일이 달라집니다. 우선순위를 변경하지 않았다면 기본 순서는 템플릿 엔진이 우선순위를 가집니다.
오류 처리 페이지 상세 정보 확인하기
정적인 HTML 대신 Model을 사용할 수 있는 경우에는 단순한 오류 내용뿐만 아니라 오류의 세부 사항을 확인할 수 있습니다. 예를 들어 Thymeleaf와 같은 템플릿 엔진을 사용하면 별도의 비즈니스 수정 없이 Model에 설정된 오류 정보를 통해 화면에 데이터를 표시할 수 있습니다.
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="UTF-8">
<title>오류 페이지</title>
</head>
<body>
<div>
서버에서 문제가 발생했습니다.<br />
관리자에게 문의해주세요.
<p>경로: [[${path}]]</p>
<p>오류: [[${error}]]</p>
<p>메시지: [[${message}]]</p>
<p>오류 목록(BindingResult): [[${errors}]]</p>
<p>상태: [[${status}]]</p>
<p>발생 시간: [[${timestamp}]]</p>
<p>예외 클래스: [[${exception}]]</p>
</div>
</body>
</html>- path : 오류 발생 경로
- error : 오류
- message : 예외 메시지
- errors : 모든 오류 (BindingResult 기준)
- status : HTTP Status 코드
- timestamp : 오류 발생 시간
- exception : 예외 클래스
위에서 제시한 데이터와 관련된 설정은 다음 몇 가지 속성을 이용해 부가적인 설정이 가능합니다.
server.error.include-exception : exception의 내용 포함 여부 [false(기본), true]
server.error.include-stacktrace : stacktrace 내용 포함 여부 [naver(기본), always, on_param]
Whitelabel 오류 페이지 비활성화하기
사용자 정의 오류 페이지를 추가하는 것과 별개로 스프링 부트에서 사용되는 whitelabel을 비활성화하는 방법이 있습니다. whitelabel을 사용하지 않고 원시적인 오류 처리를 확인하고 싶으신 경우에 사용하시면 됩니다.
properties 혹은 yaml을 이용해 whitelabel 비활성화 설정하기
- application.properties
server.error.whitelabel.enabled=false- application.yml
server:
error:
whitelabel:
enabled: falseapplication.properties에 server.error.whitelabel.enabled을 설정하거나 application.yml 파일을 추가하면 whitelabel 오류 페이지가 비활성화되고 기본 애플리케이션 컨테이너(예: Tomcat)에서 정의된 오류 페이지가 표시됩니다.
enabled 속성을 변경하는 대신 ErrorMvcAutoConfiguration 빈 사용을 제외시켜 오류 처리 방식을 수정하는 방법도 있습니다.
spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfigurationspring:
autoconfigure:
exclude: org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration또 다른 방법으로는 에노테이션을 사용하는 방법이 있습니다.
@SpringBootApplication(exclude = {ErrorMvcAutoConfiguration.class})
or
@EnableAutoConfiguration(exclude = {ErrorMvcAutoConfiguration.class})위에서 언급한 모든 방법은 whitelabel 오류 페이지를 비활성화합니다. 이 글에서 진행된 내용은 github를 통해 확인할 수 있으며, 아래의 첨부파일로도 제공합니다.
'프로그래밍 > 스프링' 카테고리의 다른 글
| Spring boot - Major Version 업데이트 JPA QueryDsl 문제 해결 (2.7.3 > 3.1.3) (0) | 2023.09.11 |
|---|---|
| Spring Security - MySql Password()을PasswordEncoder로 구현하는 방법 (0) | 2022.02.18 |
| Spring - 실무에서 사용하는 React + SpringBoot 프로젝트 만들기 with Gradle (4) | 2021.09.01 |
| Spring boot - vuejs를 사용하는 스프링 부트 프로젝트 만들기 (0) | 2021.08.25 |
| Spring error - Failed to configure a DataSource 에러 원인과 해결 방법 (0) | 2021.08.18 |