Spring REST 오류 응답과 문제 상세 관리

HTTP 오류 응답에 문제 상세 정보 담기

Spring에서는 오류가 발생했을 때, 단순히 코드만 전달하는 게 아니라 RFC 9457 규격을 따라 문제 상황에 대한 구체적인 정보를 JSON 형식으로 넣어 보낼 수 있습니다. 예외가 발생하면 상태 코드, 설명, 관련 데이터 등을 함께 응답 바디에 포함할 수 있어, 클라이언트가 쉽게 문제를 파악할 수 있습니다.

핵심 추상화: ProblemDetail과 ErrorResponse

문제 상세 정보는 ProblemDetail이라는 객체에 담깁니다. 이 객체는 규격에 맞는 필드뿐만 아니라, 프로젝트에 맞게 추가적인 정보(비표준 필드)도 넣을 수 있도록 설계되었습니다. ErrorResponse는 HTTP 상태, 헤더, 바디를 묶어서 관리하며 모든 Spring MVC 예외는 이 인터페이스를 구현합니다.

예외 처리와 응답 렌더링

@ExceptionHandler나 @RequestMapping에서 ProblemDetail 또는 ErrorResponse를 반환하면, 자동으로 RFC 9457 JSON 응답이 만들어집니다. Jackson 변환기가 "application/problem+json" 포맷을 우선적으로 사용하며, 필요한 경우 URL 경로 등도 자동으로 채워줍니다.

ResponseEntityExceptionHandler 활용

Spring에서 예외를 공통적으로 처리하려면 ResponseEntityExceptionHandler를 상속하여 @ControllerAdvice로 등록할 수 있습니다. 이 핸들러는 ErrorResponse 계열 예외를 받아 적절한 오류 응답으로 변환합니다. 또한 필요한 경우 예외를 ProblemDetail의 하위 클래스로 만들어 비표준 필드를 추가하는 것도 가능합니다.

RFC 9457 확장: 비표준 필드 추가

문제 상세 정보에 프로젝트별로 더 많은 데이터를 넣고 싶을 때는, ProblemDetail의 "properties" 맵에 직접 항목을 추가하거나, 클래스를 확장해서 전용 필드를 추가할 수 있습니다. Jackson은 이 필드들을 JSON의 최상위 항목으로 자동 반영합니다.

오류 메시지의 커스터마이징과 다국어 지원

에러 메시지의 코드와 상세 내용은 MessageSource를 통해 외부에서 정의한 메시지로 변환할 수 있습니다. 이를 활용하면, 에러 응답을 다국어로 보여주거나, 구현 내부 정보를 숨기고 친숙한 메시지로 바꿀 수 있습니다. 각 에러 타입에 따라 메시지 코드와 인자를 다르게 설정할 수 있어 세밀한 제어가 가능합니다.

특정 예외별 메시지 전략

예를 들어, 미디어 타입 오류, 요청 파라미터 누락, 타입 불일치 등 각 예외마다 어떠한 정보(지원 미디어 타입, 누락된 변수명 등)를 메시지 인자로 넘길 수 있습니다. 단순한 에러뿐 아니라, 검증 오류도 각각의 에러 항목을 세밀하게 다국어로 변환 가능합니다.

클라이언트에서 오류 응답 활용 방법

Spring의 WebClient나 RestTemplate을 사용하는 클라이언트는 오류 발생 시 getResponseBodyAs로 받은 JSON을 직접 ProblemDetail이나 그 하위 타입으로 변환해 처리할 수 있습니다. 이렇게 받은 정보로, 어떤 문제가 발생했는지 코드적으로 대응할 수 있습니다.

출처 및 참고 : Error Responses :: Spring Framework