🌱 Spring Boot 에러 처리 페이지 만들기

GODORI·2019년 4월 21일

404 Spring boot error springMVC status code 스프링부트

스프링부트 웹 MVC 프로젝트에서 상태 코드에 따라 에러를 처리하고 뷰에 각각의 에러 페이지를 보여주는 웹 사이트를 만들어 보겠습니다.

🌱 웹 페이지 에러 처리

만약 Github에서 존재하지 않는 페이지로 접속할 경우 옥토비-완이 여러분을 맞아줍니다. 스프링 부트에서는 간단히 특정 위치에 html페이지만 추가해 주면 이런 에러 페이지를 구현할 수 있습니다.

🌱 프로젝트 생성

스프링부트에서 새로운 프로젝트를 생성하는 방법은 두 가지가 있습니다.

IntelliJ ULTIMATE 버전을 사용한다면 IDE에서 새 프로젝트를 생성합니다.

Spring Initializr

Spring Initializr에 접속하여 새로운 프로젝트를 생성하고 .zip 파일로 다운받을 수 있습니다. 프로젝트 메타 데이터를 수정하고 web 의존성을 검색하여 Spring MVC and Tomcat을 추가해준 다음 Generate Project 버튼을 클릭하여 프로젝트를 다운받습니다.

저는 두 번째 방법인 Spring Initializr를 사용하여 ErrorHandle 이라는 이름의 프로젝트를 생성했습니다.

🌱 스프링의 기본 에러 처리

생성한 스프링 프로젝트를 열고 기본 프로젝트가 셋팅된 그대로 서버를 실행합니다. 브라우저에서http://localhost:8080 주소로 접속하면 다음과 같은 에러 페이지를 볼 수 있습니다.

이 에러 페이지는 Tomcat에서 만들어지는 것이 아니라 스프링부트에 의해 만들어진 페이지입니다. 스프링에서 이런 기본적인 에러 처리를 하는 곳은 BasicErrorController입니다.

BasicErrorController

    // ...
    
    // text/html가 포함된 헤더가 있는 요청에는 뷰를 반환
    @RequestMapping(produces = {"text/html"})
    public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
        HttpStatus status = this.getStatus(request);
        Map<String, Object> model = Collections.unmodifiableMap(this.getErrorAttributes(request, this.isIncludeStackTrace(request, MediaType.TEXT_HTML)));
        response.setStatus(status.value());
        ModelAndView modelAndView = this.resolveErrorView(request, response, status, model);
        return modelAndView != null ? modelAndView : new ModelAndView("error", model);
    }
    
    // 그 외에는 json 객체를 반환
    @RequestMapping
      public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
          Map<String, Object> body = this.getErrorAttributes(request, this.isIncludeStackTrace(request, MediaType.ALL));
          HttpStatus status = this.getStatus(request);
          return new ResponseEntity(body, status);
      }
    
    // ...

BasicErrorController 코드의 해당 부분은 HTTP 요청의 Accept 헤더에 text/html가 포함된 경우엔 html 뷰를 반환하고, 그 외에는 json 객체를 결과로 반환합니다. 위의 Whitelabel Error Page는 전자의 경우가 됩니다.

반대로, 웹 브라우저가 아니라 콘솔에서 curl로 헤더 없이 페이지를 요청하면 json 형태의 에러 메시지를 전달받습니다.

curl http://localhost:8080/

{"timestamp":"2019-04-19T00:32:38.982+0000","status":404,"error":"Not Found","message":"No message available","path":"/"}

헤더에 Accept: text/html 을 추가하면 웹 브라우저와 동일하게 html 뷰를 반환합니다.

curl -H "Accept: text/html" http://localhost:8080

<html><body><h1>Whitelabel Error Page</h1><p>This application has no explicit mapping for /error, so you are seeing this as a fallback.</p><div id='created'>Fri Apr 19 17:01:20 KST 2019</div><div>There was an unexpected error (type=Not Found, status=404).</div><div>No message available</div></body></html>

🌱 정상 동작 페이지 생성

http://localhost:8080 주소로 접근하면 현재는 스프링이 BasicErrorController를 통해 생성한 Whitelabel Error Page만 볼 수 있습니다. 이 에러 페이지는 설정 파일에 server.error.path나 error.path가 없을 경우 마지막으로 스프링이 만들어주는 에러 페이지입니다.

Whitelabel Error Page를 제거하기 위해, 먼저 루트 주소("/")에 대해서는 index.html을 추가하여 정상적으로 접근되는 페이지를 만들겠습니다.

index.html은 정적 리소스 맵핑 시 사용하는 리소스 기본 경로 중 아무곳에나 위치시켜도 됩니다.

classpath:/static
classpath:/public
classpath:/resources
classpath:/META-INF/resources

저는 src/main/resources/static 위치에 index.html과 이미지 파일을 하나 추가했습니다.

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <title>Title</title>
  </head>
  <body>
    <img src="toto.jpeg" width="300" height="400" alt="index cat">
    <h1>Hello, Godori!</h1>
  </body>
</html>

서버를 실행하여 루트로 접속하면 정상적으로 index.html이 보입니다.

🌱 커스텀 에러 페이지 만들기

https://http.cat 은 상태 코드를 고양이 사진으로 표현한 재밌는 사이트입니다.

Github의 404 에러 페이지처럼, 특정 상태 코드에 따라 서로 다르게 처리해주는 커스텀 에러 페이지를 다음 HTTP Cats의 이미지를 이용해 만들어 볼게요.

resources의 static 디렉토리 안에 error 디렉토리를 만들고 404.html과 5xx.html 파일 두 개를 생성합니다. 페이지 이름은 상태 코드와 동일하게 404 등으로 적거나, 500번대 상태에 대해 처리한다는 의미로 5xx.html등으로 생성할 수 있습니다.

(만약 static 디렉토리 안의 디렉토리가 error 하나 뿐이라면 디렉토리 이름이 static.error 라는 형태로 보일 수도 있습니다)

404와 500 에러에 대해 각각의 html 페이지를 구성하고, SampleController 라는 이름의 Controller를 생성하여 localhost:8080/error 로 접속하면 에러를 던지는 페이지를 만듭니다.

    package com.godori.ErrorHandle;
    
    import org.springframework.stereotype.Controller;
    import org.springframework.web.bind.annotation.GetMapping;
    
    @Controller
    public class SampleController {
    
        @GetMapping("/error")
        public String errorpage(){
            throw new IllegalStateException("Error");
        }
    }