ProblemDetail

RFC 7807

클라이언트 요청에서 에러가 발생했을 때, 우리는 에러가 발생했다고 알려주기 위해 오류 메시지를 보내야 한다. 하지만 이 오류 메시지에는 어떤 내용을 담아야 할까?

이에 대한 규약을 정해준 것이 바로 RFC 7807이다. RFC 7807은 API 에러 응답에 대한 규약을 정의한 문서이고 현재 Standard Track으로 표준화되었다.

RFC 7807에서 제시한 오류 메시지 구조는 총 5개의 필드로 구성되어 있다.

• type : 에러를 분류하기 위한 URI 식별자
• title : 에러에 대한 간략한 설명
• status : HTTP response code
• detail : 에러에 대한 자세한 설명
• instance : 에러가 발생한 URI

ProblemDetail

ProblemDetail 클래스는 이 RFC 7807 표준을 따라 Spring 에서 새롭게 만든 클래스이다. 스프링 프레임워크 6.0.x 버전부터 사용을 할 수 있고, RFC 7807 Problem Detail for API 문서 이름의 응답 객체 명세 이름을 그대로 사용하였다.

ProblemDetail 클래스는 기본적으로 아래와 같은 필드를 가지고 있다.

public class ProblemDetail {

    /**
     * 문제 유형을 식별하는 URI 참조.
     * 이 URI가 참조되면 문제 유형에 대한 문서를 제공해야 한다.
     * 값이 없는 경우 "about:blank"으로 가정된다.
     */
    private static final URI BLANK_TYPE = URI.create("about:blank");
    private URI type;

    /**
     * 문제 유형에 대한 사람이 읽을 수 있는 간단한 요약
     */
    @Nullable
    private String title;

    /**
     * 이 문제의 응답 Http status 코드
     */
    private int status;

    /**
     * 문제의 발생에 대한 사람이 읽을 수 있는 구체적인 설명
     */
    @Nullable
    private String detail;

    /**
     * 문제가 발생한 URI
     */
    @Nullable
    private URI instance;
}

더 자세한 내용은 해당 링크를 참조하길 바란다.

ProblemDetail을 사용한 예외처리

기존

아래의 코드는 ProblemDetail을 사용하지 않고 예외처리를 진행한 코드들이다.

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler
    public ResponseEntity<String> handleCodeZapException(CodeZapException codeZapException) {
        return new ResponseEntity<>(codeZapException.getMessage(), codeZapException.getStatus());
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler
    public ResponseEntity<ExceptionResponse> handleCodeZapException(CodeZapException codeZapException) {
        return ResponseEntity.status(codeZapException.getStatus())
                .body(codeZapException.getMessage());
    }
}

RFC 7807 표준을 따르지도 못했고, 만약 따른다면 굉장히 긴 코드가 될 것이다.

변경

위 코드들을 ProblemDetail을 사용하여 다시 작성해보자.

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler
    public ResponseEntity<ProblemDetail> handleCodeZapException(CodeZapException codeZapException) {
        return ResponseEntity.status(codeZapException.getHttpStatusCode())
                .body(ProblemDetail.forStatusAndDetail(
                        codeZapException.getHttpStatusCode(),
                        codeZapException.getMessage())
                );
    }
}

굉장히 간단하게 RFC 7807 표준을 따를 수 있게 되었다.

해당 코드를 사용하여 에러를 발생시키면 아래와 같은 응답이 오게 된다.

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "식별자 1에 해당하는 템플릿이 존재하지 않습니다.",
  "instance": "/templates/1"
}

title과 instance

여기서 궁금한 점이 발생하게 된다.

나는 다음과 같이 status와 detail만 전달해주었다.

return ResponseEntity.status(codeZapException.getHttpStatusCode())
        .body(ProblemDetail.forStatusAndDetail(
        codeZapException.getHttpStatusCode(),
        codeZapException.getMessage())
    );

하지만 어떻게 title에는 NOT FOUND가 들어가고, instance에는 해당 에러가 발생한 URI인 /templates/1이 들어가게 되는 것일까?

결론부터 이야기하면 instance의 경우는 정확한 이유를 찾지 못했다. 추후에 알게 된다면 해당 내용을 추가하도록 하겠다.

title의 경우에는 ProblemDetail의 내부 구현에 정답이 있었다. 다음은 ProblemDetail 내부에서 구현되어 있는 코드 중 우리의 코드에서 사용되는 부분들이다.

public class ProblemDetail {

    protected ProblemDetail(int rawStatusCode) {
        this.type = BLANK_TYPE;
        this.status = rawStatusCode;
    }

    @Nullable
    public String getTitle() {
        if (this.title == null) {
            HttpStatus httpStatus = HttpStatus.resolve(this.status);
            if (httpStatus != null) {
                return httpStatus.getReasonPhrase();
            }
        }
        return this.title;
    }

    public static ProblemDetail forStatus(int status) {
        return new ProblemDetail(status);
    }

    public static ProblemDetail forStatusAndDetail(HttpStatusCode status, @Nullable String detail) {
        Assert.notNull(status, "HttpStatusCode is required");
        ProblemDetail problemDetail = forStatus(status.value());
        problemDetail.setDetail(detail);
        return problemDetail;
    }
}

위와 같이 우리는 status와 detail 정보만 전달해줬지만 getTitle()을 할 때 만약 title이 null 이라면 전달 받은 HttpStatus에서 정보를 가져오는 것을 알 수 있다.

이와 같이 우리는 스프링에서 제공해주는 ProblemDetail 클래스를 이용하여 손쉽게 에러 메시지를 전달해줄 수 있게 되었다.