웹 애플리케이션 에러 처리 가이드 (RFC 9457, 스프링 부트)

"errors": [ { "detail": "must be a positive integer", "pointer": "#/age" }, { "detail": "must be 'green', 'red' or 'blue'", "pointer": "#/profile/color" } ]

spring: mvc: # RFC 9457 Problem Details for HTTP APIs 지원 활성화 problem-details: enabled: true

public class ErrorResponseException extends NestedRuntimeException implements ErrorResponse { ... private final ProblemDetail body; ...

public class ProblemDetail implements Serializable { private static final URI BLANK_TYPE = URI.create("about:blank"); private URI type = BLANK_TYPE; @Nullable private String title; private int status; @Nullable private String detail; @Nullable private URI instance; @Nullable private Map<String, Object> properties;

import org.springframework.http.HttpStatus; import org.springframework.http.ProblemDetail; import org.springframework.web.ErrorResponseException; ProblemDetail pd = ProblemDetail.forStatusAndDetail( HttpStatus.FORBIDDEN, // status "물건 가격은 1,000원인데 계좌에 0원밖에 없습니다." // detail ); pd.setTitle("잔액이 부족합니다."); pd.setType(URI.create("https://pay.gyuray.dev/errors/not-enough-balance")); throw new ErrorResponseException(HttpStatus.FORBIDDEN, pd, null);

{ "type": "https://pay.gyuray.dev/errors/not-enough-balance", "title": "잔액이 부족합니다.", "status": 403, "detail": "물건 가격은 1,000원인데 계좌에 0원밖에 없습니다.", "instance": "/api/payment/123" }

@RestControllerAdvice @RequiredArgsConstructor @Slf4j public class GlobalExceptionHandler { /** * 별도로 핸들링되지 않는 에러를 default로 처리하는 전역 핸들러 */ @ExceptionHandler(Exception.class) public ProblemDetail handleAllExceptions( Exception ex, HttpServletRequest request ) { ProblemDetail pd = ProblemDetail.forStatusAndDetail( HttpStatus.INTERNAL_SERVER_ERROR, // status "서버측 에러가 발생했습니다." // detail ); pd.setTitle("Internal Server Error"); pd.setType(URI.create("https://pay.gyuray.dev/errors/internal-server-error")); return pd; } }

public class ErrorUtils { /** * 필드 검증 오류 내역을 담는 레코드 * pointer: 오류가 발생한 JSON 필드의 JSON Pointer (예: "#/username") * detail: 해당 필드에 대한 오류 설명 (예: "Username must not be empty") */ public record FieldError(String pointer, String detail) { } /** * RFC 9457 규격에 맞는 ErrorResponseException을 생성 */ public ErrorResponseException createException( HttpStatus status, String title, String detail, ErrorType errorType, Map<String, Object> properties ) { ProblemDetail pd = ProblemDetail.forStatusAndDetail(status, detail); pd.setTitle(title); pd.setType(URI.create("https://xxx.gyuray.dev/errors/" + errorType.getTypePath())); if (properties != null) { properties.forEach(pd::setProperty); } return new ErrorResponseException(status, pd, null); } /** * 400 Bad Request */ public ErrorResponseException badRequest(String detail) { return createException(HttpStatus.BAD_REQUEST, HttpStatus.BAD_REQUEST.getReasonPhrase(), detail, ErrorType.BAD_REQUEST, null); } ... /** * 422 Unprocessable Content */ public ErrorResponseException unprocessableContent( String detail, List<FieldError> fieldErrors ) { Map<String, Object> properties = null; if (fieldErrors != null && !fieldErrors.isEmpty()) { properties = Map.of("errors", fieldErrors); } // RFC 4918 -> RFC 9110으로 넘어오면서 Unprocessable Entity에서 Unprocessable Content로 명칭이 변경됨 return createException(HttpStatus.UNPROCESSABLE_ENTITY, "Unprocessable Content", detail, ErrorType.UNPROCESSABLE_CONTENT, properties); } /** * 500 Internal Server Error */ public ErrorResponseException internalServerError() { return createException(HttpStatus.INTERNAL_SERVER_ERROR, HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(), "An unexpected error occurred on the server.", ErrorType.INTERNAL_SERVER_ERROR, null); } }

@ExceptionHandler(Exception.class) public ProblemDetail handleAllExceptions( Exception ex, HttpServletRequest request ) { // Exception 객체를 생성 후 응답용 데이터 추출 ErrorResponseException errorResponse = errorUtils.internalServerError(); ProblemDetail pd = errorResponse.getBody(); return pd; }

{ ... "instance": "https://xxx.gyuray.dev/api/payment/123?errorId=abc" ... }

public String setInstanceForProblemDetail( ProblemDetail pd, HttpServletRequest request ) { String errorId = UUID.randomUUID().toString().substring(0, 8); pd.setInstance(URI.create(problemDetailProperty.baseUrl() + request.getRequestURI() + "?errorId=" + errorId)); return errorId; }

@ExceptionHandler(Exception.class) public ProblemDetail handleAllExceptions( Exception ex, HttpServletRequest request ) { // Exception 객체를 생성 후 응답용 데이터 추출 ErrorResponseException errorResponse = errorUtils.internalServerError(); ProblemDetail pd = errorResponse.getBody(); String errorId = errorUtils.setInstanceForProblemDetail(pd, request); return pd; }

@RestControllerAdvice @Order(Ordered.HIGHEST_PRECEDENCE) @RequiredArgsConstructor @Slf4j public class GlobalExceptionHandler { private final ErrorUtils errorUtils; @ExceptionHandler(ErrorResponseException.class) public ProblemDetail handleErrorResponse( ErrorResponseException ex, HttpServletRequest request ) { ProblemDetail pd = ex.getBody(); String errorId = errorUtils.setInstanceForProblemDetail(pd, request); return pd; }

spring: mvc: # RFC 9457 Problem Details for HTTP APIs 지원 활성화 problem-details: enabled: true

public ErrorResponseException createException( HttpStatus status, String title, String detail, ErrorType errorType, Map<String, Object> properties, Throwable cause ) { ProblemDetail pd = ProblemDetail.forStatusAndDetail(status, detail); pd.setTitle(title); pd.setType(URI.create(problemDetailProperty.baseUrl() + errorType.getTypePath())); if (properties != null) { properties.forEach(pd::setProperty); } return new ErrorResponseException(status, pd, cause); } public ErrorResponseException createException( HttpStatus status, String title, String detail, ErrorType errorType, Map<String, Object> properties ) { return createException(status, title, detail, errorType, properties, null); }

/** * 500 Internal Server Error */ public ErrorResponseException internalServerError(Throwable cause) { return createException( HttpStatus.INTERNAL_SERVER_ERROR, HttpStatus.INTERNAL_SERVER_ERROR.getReasonPhrase(), "An unexpected error occurred on the server.", ErrorType.INTERNAL_SERVER_ERROR, null, cause ); } public ErrorResponseException internalServerError(Throwable cause, String log) { return internalServerError(new RuntimeException(log, cause)); }

try { Files.createDirectories(recordDirPath); } catch (IOException e) { throw errorUtils.internalServerError(e, String.format("Failed to create record directory for [%s] at path: %s", name, recordDirPath)); }

@ExceptionHandler(ErrorResponseException.class) public ProblemDetail handleErrorResponse( ErrorResponseException ex, HttpServletRequest request ) { ProblemDetail pd = ex.getBody(); String errorId = errorUtils.setInstanceForProblemDetail(pd, request); if (pd.getStatus() >= 500) { // 서버 에러인 경우 원본 예외(커스텀 RuntimeException)를 꺼내서 로깅 Throwable rootCause = ex.getCause() != null ? ex.getCause() : ex; log.error("errorId={} status={} path={}", errorId, pd.getStatus(), request.getRequestURI(), rootCause); } return pd; }