Spring MVC - 예외 처리(1)

샘플 애플리케이션을 구현해보면서 만날 수 있는 예외는 다음과 같다.

 

• 클라이언트 요청 데이터에 대한 유효성 검증(Validation)에서 발생하는 예외
• 서비스 계층의 비즈니스 로직에서 던져지는 의도된 예외
• 웹 애플리케이션 실행 중에 발생하는 예외(RuntimeException)

 

DTO 유효성 검증 측에서 클라이언트의 요청 데이터 유효성 검증에 실패할 경우, 다음과 같은 응답 메시지를 확인 가능하다.

다음과 같은 Response Body 내용만으로는 요청 데이터 중에서 어떤 항목이 유효성 검증에 실패했는지 알 수 없다. 

클라이언트 쪽에서 에러 메시지를 조금 더 구체적으로 친절하게 알 수 있도록 바꾸는 작업이 필요하다.

 

 

💡@ExceptionHandler를 이용한 Controller 레벨에서의 예외 처리

 

클라이언트가 전달받는 Request Body는 애플리케이션에서 예외가 발생했을 때, 내부적으로 Spring에서 전송해주는 에러 응답 메시지 중 하나. Spring이 처리하는 에러 응답 메시지를 우리가 직접 처리하도록 코드를 수정해보자.

 

Spring에서의 예외는 애플리케이션에 문제가 발생한 경우, 이를 알려서 처리하는 것뿐만 아니라 유효성 검증에 실패했을 때와 같이 이 실패를 하나의 예외로 간주하여 이 예외를 던져서(throw) 예외 처리를 유도함.

 

package com.codestates.member.controller;

import com.codestates.member.dto.MemberPatchDto;
import com.codestates.member.dto.MemberPostDto;
import com.codestates.member.dto.MemberResponseDto;
import com.codestates.member.entity.Member;
import com.codestates.member.mapper.MemberMapper;
import com.codestates.member.service.MemberService;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;

import javax.validation.Valid;
import javax.validation.constraints.Positive;
import java.util.List;


/**
 * - DI 적용
 * - Mapstruct Mapper 적용
 */
@RestController
@RequestMapping("/v6/members")
@Validated
@Slf4j
public class MemberControllerV6 {
    private final MemberService memberService;
    private final MemberMapper mapper;

    public MemberControllerV6(MemberService memberService, MemberMapper mapper) {
        this.memberService = memberService;
        this.mapper = mapper;
    }

    @PostMapping
    public ResponseEntity postMember(@Valid @RequestBody MemberPostDto memberDto) {
        Member member = mapper.memberPostDtoToMember(memberDto);

        Member response = memberService.createMember(member);

        return new ResponseEntity<>(mapper.memberToMemberResponseDto(response),
                HttpStatus.CREATED);
    }

    @PatchMapping("/{member-id}")
    public ResponseEntity patchMember(
            @PathVariable("member-id") @Positive long memberId,
            @Valid @RequestBody MemberPatchDto memberPatchDto) {
        memberPatchDto.setMemberId(memberId);

        Member response =
                memberService.updateMember(mapper.memberPatchDtoToMember(memberPatchDto));

        return new ResponseEntity<>(mapper.memberToMemberResponseDto(response),
                HttpStatus.OK);
    }

    ...

    @ExceptionHandler
    public ResponseEntity handlerException(MethodArgumentNotValidException e){
        final List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();
        return new ResponseEntity<>(fieldErrors, HttpStatus.BAD_REQUEST);
    }
}

• 클라이언트 쪽에서 회원 등록을 위해 MemberController 의 postMember() 핸들러 메서드에 요청을 전송함.
• RequestBody 에 유효하지 않은 요청 데이터가 포함되어 있어 유효성 검증에 실패하고, MethodArgumentNotValidException 이 발생함.
• MemberController 에는 @ExceptionHandler 애너테이션이 추가된 예외 처리 메서드인 handlerException() 이 있기 때문에 유효성 검증 과정에서 내부적으로 던져진 MethodArgumentNotValidException 을 handleException() 메서드가 전달받음.
• (1)과 같이 MethodArgumentNotValidException 객체에서 getBindingResult().getFieldErrors() 를 통해 발생한 에러 정보를 확인 가능함.
• (1)에서 얻은 에러 정보를 (2)에서 ResponseEntity 를 통해 Response Body로 전달함.

 

회원 등록 정보에서 유효하지 않은 이메일 주소를 포함해 요청을 전송한 결과로 Response Body를 보면 이전과 다른 응답 메시지를 전달 받은 것을 알 수 있음.

[
    {
        "codes": [
            "Email.memberPostDto.email",
            "Email.email",
            "Email.java.lang.String",
            "Email"
        ],
        "arguments": [
            {
                "codes": [
                    "memberPostDto.email",
                    "email"
                ],
                "arguments": null,
                "defaultMessage": "email",
                "code": "email"
            },
            [],
            {
                "defaultMessage": ".*",
                "codes": [
                    ".*"
                ],
                "arguments": null
            }
        ],
        "defaultMessage": "must be a well-formed email address",
        "objectName": "memberPostDto",
        "field": "email",
        "rejectedValue": "jeein@",
        "bindingFailure": false,
        "code": "Email"
    }
]

유효성 검사 실패에 대한 에러 메시지를 구체적으로 전달해주기 때문에 클라이언트 입장에서는 이제 어느 곳에 문제가 있는지를 구체적으로알 수 있게 됨.

그런데 클라이언트 입장에서는 의미를 알 수 없는 정보를 전부 포함한 Response Body 전체 정보를 굳이 다 전달 받을 필요는 없어 보임.

요청 전송시, Request Body의 JSON 의 프로퍼티 중에서 문제가 된 프로퍼티는 무엇인지와 에러 메시지 정도만 전달받아도 충분!

에러 정보를 기반으로 한 Error Response 클래스를 만들어서 필요한 정보를 담은 후에 클라이언트 쪽에 전달해주면 됨.

 

 

💡ErrorResponse 클래스 적용

package com.codestates.response.v1;

import lombok.AllArgsConstructor;
import lombok.Getter;
import org.springframework.validation.FieldError;

import java.util.List;


@Getter
@AllArgsConstructor
public class ErrorResponse {
    private List<FieldError> fieldErrors;

    @Getter
    @AllArgsConstructor
    public static class FieldError{
        private String field;
        private Object rejectedValue;
        private String reason;
    }
}

DTO 클래스의 유효성 검증 실패 시, 실패한 필드(멤버 변수)에 대한 Error정보만 담아서 응답으로 전송하기 위한 ErrorResponse 클래스.

Response Body를 보면 JSON 응답 객체가 배열인 것을 알 수 있음.

배열인 이유를 생각해 보면 DTO 클래스에서 검증해야 되는 멤버 변수에서 유효성 검증에 실패하는 멤버 변수들이 하나 이상이 될 수 있기 때문에 유효성 검증 실패 에러 역시 하나 이상이 될 수 있다는 의미.

한 개의 필드 에러 정보는 FieldError 라는 별도의 static class를 ErrorResponse 클래스의 멤버 클래스로 정의.

 

package com.codestates.member.controller.controller_v7;

import com.codestates.member.dto.MemberPostDto;
import com.codestates.member.entity.Member;
import com.codestates.response.v1.ErrorResponse;
import lombok.extern.slf4j.Slf4j;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.*;
import javax.validation.Valid;
import java.util.List;
import java.util.stream.Collectors;

@RestController
@RequestMapping("/v7/members")
@Validated
@Slf4j
public class MemberControllerV7 {
    ...
		...

    @PostMapping
    public ResponseEntity postMember(@Valid @RequestBody MemberPostDto memberDto) {
        Member member = mapper.memberPostDtoToMember(memberDto);

        Member response = memberService.createMember(member);

        return new ResponseEntity<>(mapper.memberToMemberResponseDto(response),
                HttpStatus.CREATED);
    }

		...
		...

    @ExceptionHandler
    public ResponseEntity handleException(MethodArgumentNotValidException e) {
        // (1)
        final List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();

        // (2)
        List<ErrorResponse.FieldError> errors =
                fieldErrors.stream()
                            .map(error -> new ErrorResponse.FieldError(
                                error.getField(),
                                error.getRejectedValue(),
                                error.getDefaultMessage()))
                            .collect(Collectors.toList());

        return new ResponseEntity<>(new ErrorResponse(errors), HttpStatus.BAD_REQUEST);
    }
}

(2)와 같이 필요한 정보들만 선택적으로 골라서 ErrorResponse.FieldError 클래스에 담아서 List로 변환 후, List<ErrorResponse.FieldError>를 ResponseEntity 클래스에 실어서 전달

 

💡@ExceptionHandler의 단점

 

@ExceptionHandler 애너테이션과 ErrorResponse 클래스를 이용해서 Request Body에 대한 유효성 검증 실패 시 필요한 에러 정보만 담아서 클라이언트에게 응답으로 전송할 수 있게 됨.

 

하지만, 각각의 Controller 클래스에서 @ExceptionHandler 애너테이션을 사용하여 Request Body에 대한 유효성 검증 실패에 대한 에러 처리를 해야 되므로 각 Controller 클래스마다 코드 중복이 발생함.

Controller에서 처리해야 되는 예외(Exception)가 유효성 검증 실패에 대한 예외(MethodArgumentNotValidException)만 있는 것이 아니기 때문에 하나의 Controller 클래스 내에서 @ExceptionHandler를 추가한 에러 처리 핸들러 메서드가 늘어남.

@ExceptionHandler
public ResponseEntity handleException(ConstraintViolationException e){
    return new ResponseEntity(HttpStatus.BAD_REQUEST);
}

patchMember() 핸들러 메서드의 URI 변수인 "/{member-id}" 에 0이 넘어올 경우, ConstraintViolationException이 발생하기 때문에 ConstraintViolationException 을 처리할 @ExceptionHandler를 추가한 메서드를 하나 더 추가함.

이처럼 @ExceptionHandler 애너테이션을 사용한 방식은 코드 중복과 유연하지 않은 예외 처리 방식이기 때문에 예외 처리에 대한 개선이 필요함.

 

 

💡@RestControllerAdvice를 사용한 예외 처리 공통화

 

특정 클래스에 @RestControllerAdvice 애너테이션을 추가하면 여러 개의 Controller 클래스에서 @ExceptionHandler, @InitBinder, 또는 @ModelAttribute 가 추가된 메서드를 공유해서 사용 가능함.

 

cf. @InitBinder는 요청 매개변수를 Java Bean 객체에 바인딩하는 데 사용되는 WebDataBinder 인스턴스를 초기화하는 메서드를 정의하는 데 사용되는 주석. 

@InitBinder, @ModelAttribute 애너테이션은 JSP, Thymeleaf 같은 서버 사이드 렌더링(SSR, Server Side Rendering) 방식에서 주로 사용되는 방식.

 

이 말의 의미를 예외 처리 관점에서 보면, @RestControllerAdvice 애너테이션을 추가한 클래스를 이용하면 예외 처리를 공통화할 수 있다는 것.

 

💡ExceptionAdvice 클래스 정의

 

Controller 클래스에서 발생하는 예외들을 공통으로 처리할 ExceptionAdvice 클래스를 다음과 같이 정의.

package com.codestates.advice;

import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionAdvice {
    
}

예외를 처리할 ExceptionAdvice 클래스에 @RestControllerAdvice 애너테이션을 추가하면 이 클래스는 이제 Controller 클래스에서 발생하는 예외를 도맡아서 처리하게 됨.

 

 

💡Exception 핸들러 메서드 구현

package com.codestates.advice;

import com.codestates.response.v1.ErrorResponse;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import javax.validation.ConstraintViolationException;
import java.util.List;
import java.util.stream.Collectors;

@RestControllerAdvice
public class GlobalExceptionAdvice {
    //(1)
    public ResponseEntity handleMethodArgumentNotValidException(MethodArgumentNotValidException e){
        final List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors();
        
        List<ErrorResponse.FieldError> errors=
                fieldErrors.stream()
                        .map(error->new ErrorResponse.FieldError(
                                error.getField(),
                                error.getRejectedValue(),
                                error.getDefaultMessage()
                        ))
                        .collect(Collectors.toList());
        
        return new ResponseEntity<>(new ErrorResponse(errors), HttpStatus.BAD_REQUEST);
    }
    
    //(2)
    @ExceptionHandler
    public ResponseEntity handleConstraintViolationException(ConstraintViolationException e){
        return new ResponseEntity<>(HttpStatus.BAD_REQUEST);
    }
}

@RestControllerAdvice 애너테이션을 이용해서 예외 처리를 공통화하면 각 Controller마다 추가되는 @ExceptionHandler 로직에 대한 중복 코드를 제거하고, Controller의 코드를 단순화할 수 있음.

 

 

💡ErrorResponse 수정

 

GlobalExceptionAdvice를 통해 Controller 클래스에서 발생하는 RequestBody의 유효성 검증에 대한 에러는 유연한 처리가 가능해짐.

URI 변수로 넘어오는 값의 유효성 검증에 대한 에러(ConstraintViolationException)처리는 아직 구현되지 않음.

ConstraintViolationException에 대한 처리도 할 수 있도록 함. 이 부분을 처리하기 전에 먼저 ErrorResponse 클래스가 ConstraintViolationException에 대한 Error Response를 생성할 수 있도록 ErrorResponse 클래스를 수정.

package com.codestates.response.v1;

import lombok.Getter;
import org.springframework.validation.BindingResult;
import org.springframework.validation.FieldError;

import javax.validation.ConstraintViolation;
import java.util.List;
import java.util.Set;
import java.util.stream.Collectors;


@Getter
public class ErrorResponse {
    //(1)유효성 검증에 실패한 필드의 에러 정보를 담는 멤버 변수.
    private List<FieldError> fieldErrors;

    //(2)URI 변수 값의 유효성 검증에 실패로 발생한 에러 정보를 담는 멤버 변수
    private List<ConstraintViolationError> violationErrors;

    //(3)ErrorResponse 생성자에 private 접근 제한자를 지정함으로써 of() 메서드를 이용해야 하며, 이를 통해 객체를 생성함과 동시에 ErrorResponse 역할을 명확하게 해 줌.
    private ErrorResponse(List<FieldError> fieldErrors, List<ConstraintViolationError> violationErrors) {
        this.fieldErrors = fieldErrors;
        this.violationErrors = violationErrors;
    }

    //(4)BindingResult에 대한 ErrorResponse 객체 생성
    public static ErrorResponse of(BindingResult bindingResult){
        return new ErrorResponse(FieldError.of(bindingResult), null);
    }

    //(5)Set<ConstraintViolation<?>> 객체 에 대한 ErrorResponse 객체 생성
    public static ErrorResponse of(Set<ConstraintViolation<?>> violations){
        return new ErrorResponse(null, ConstraintViolationError.of(violations));
    }

    //(6) Field Error 가공, 필드의 유효성 검증에서 발생하는 에러 정보를 생성함.
    @Getter
    public static class FieldError{
        private String field;
        private Object rejectedValue;
        private String reason;

        public FieldError(String field, Object rejectedValue, String reason) {
            this.field = field;
            this.rejectedValue = rejectedValue;
            this.reason = reason;
        }

        public static List<FieldError> of(BindingResult bindingResult){
            final List<org.springframework.validation.FieldError> fieldErrors =
                    bindingResult.getFieldErrors();
            return fieldErrors.stream()
                    .map(error->new FieldError(
                            error.getField(),
                            error.getRejectedValue()==null?
                                    "":error.getRejectedValue().toString(),
                            error.getDefaultMessage()
                    )).collect(Collectors.toList());
        }
    }

    //(7) ConstraintViolation Error 가공, URI 변수 값에 대한 에러 정보를 생성함.
    @Getter
    public static class ConstraintViolationError{
        private String propertyPath;
        private Object rejectedValue;
        private String reason;

        public ConstraintViolationError(String propertyPath, Object rejectedValue, String reason) {
            this.propertyPath = propertyPath;
            this.rejectedValue = rejectedValue;
            this.reason = reason;
        }

        public static List<ConstraintViolationError> of(Set<ConstraintViolation<?>> constraintViolations) {
            return constraintViolations.stream()
                    .map(constraintViolation -> new ConstraintViolationError(
                            constraintViolation.getPropertyPath().toString(),
                            constraintViolation.getInvalidValue().toString(),
                            constraintViolation.getMessage()
                    )).collect(Collectors.toList());
        }
    }
}

 

💡Exception 핸들러 메서드 수정

 

package com.codestates.advice;

import com.codestates.response.v1.ErrorResponse;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.FieldError;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

import javax.validation.ConstraintViolationException;
import java.util.List;
import java.util.stream.Collectors;

@RestControllerAdvice
public class GlobalExceptionAdvice {
    @ExceptionHandler
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleMethodArgumentNotValidException(MethodArgumentNotValidException e){
        final ErrorResponse response=ErrorResponse.of(e);
        return response;
    }


    @ExceptionHandler
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ErrorResponse handleConstraintViolationException(ConstraintViolationException e){
        final ErrorResponse response = ErrorResponse.of(e.getConstraintViolations());
        return response;
    }
}

Error Response 정보를 만드는 역할을 ErrorResponse 클래스가 대신해주기 때문에 코드 자체가 간결해짐.

또 하나 중요한 변경사항은 ErrorResponse 객체를 ResponseEntity로 래핑해서 리턴하는 반면, 위의 코드에서는 ResponseEntity가 사라지고 ErrorResponse 객체를 바로 리턴하고 있음.

@ResponseStatus 애너테이션을 이용해서 HTTP Status를 HTTP Response에 포함하고 있음.

 

 

💡@RestControllerAdvice vs @ControllerAdvice

 

Spring MVC 4.3 버전 이후부터 @RestControllerAdvice 애너테이션을 지원하는데, 둘 사이의 차이점은 다음과 같다.

@RestControllerAdvice = @ControllerAdvice + @RepsonseBody

@RestControllerAdvice 애너테이션은 @ControllerAdvice의 기능을 포함하고 있으며, @ResponseBody의 기능 역시 포함하고 있기 때문에 JSON 형식의 데이터를 Response Body로 전송하기 위해서 ResponseEntity로 데이터를 래핑 할 필요가 없다