Spring boot 3 - Problem Details for HTTP APIs

 

Problem Detail 이란

Spring 6 ( Spring Boot 3 ) 에서 부터 지원하게된, Error 응답에 대한 새로운 표준입니다

ErrorResponse class 를 따로 만들 필요없이, spring-web 에서 정의한 ProblemDetail class 를 사용할 수 있습니다.

https://github.com/spring-projects/spring-framework/blob/main/spring-web/src/main/java/org/springframework/http/ProblemDetail.java

 

public class ProblemDetail {

	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;

}

 

항목	설명
int status	( 필수 ) Http status code  ; 400, 403, 500
URI type	문제 유형 식별 URI 참조, Error 유형에 따른 해결법을 가이드하는 html 페이지
String title	Error 에 대한 사람이 읽을 수 있는 간단한 제목
String detail	Error 에 대한 자세한 설명, biz rule 또는 e.getMessage
URI instance	에러가 발생한  URI
Map<String, Object> properties	추가적으로 사용할 값을 설정하는 map

 

예시

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/probs/out-of-credit",
  "title": "You do not have enough credit.",
  "detail": "Your current balance is 30, but that costs 50.",
  "instance": "/account/12345/msgs/abc",
  "balance": 30,
  "accounts": ["/account/12345",
                "/account/67890"]
}


HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.net/validation-error",
  "title": "Your request parameters didn't validate.",
  "invalid-params": [ 
      {
        "name": "age",
        "reason": "must be a positive integer"
      },
      {
        "name": "color",
        "reason": "must be 'green', 'red' or 'blue'"}
    ]
}

 

 

RFC 7807 

API 에러 응답에 대한 규약을 정의한 문서입니다

https://datatracker.ietf.org/doc/html/rfc7807

 

첫 부분에 기계가 읽을 수 있는 error 의 상세 정보란 문구가 인상적입니다.

에러에 대한 상세내용을 표시하고, tpe 에 정의된 troubleshooting guide 에 따라 machine 이 스스로 에러를 debug 하려는 노력이 아닐까 추정해 봅니다.

This document defines a "problem detail" as a way to carry machine-readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP API

 

 

spring-framework 에 RFC 7807 problem-details 를 적용해 달라는 요청이 8차례나 있었고,

spring 6(spring boot3) 에 추가되었습니다

https://github.com/spring-projects/spring-framework/issues/27052

Support for problem details based on RFC 7807 · Issue #27052 · spring-projects/spring-framework

 

code example

https://github.com/gwagdalf/problemdetaildemo

GitHub - gwagdalf/problemdetaildemo

 

왼쪽 default 방식

오른쪽 : @RestControllerAdvice, @ExceptionHandler 사용 방식 비교

 

왼쪽 : @RestControllerAdvice, @ExceptionHandler 사용 방식

오른쪽 : ProblemDetail 방식 비교

 

ProblemDetail 예제코드

@RestControllerAdvice
public class AppErrorHandler {

  @ResponseStatus(code = HttpStatus.BAD_REQUEST)
  @ExceptionHandler(value = RuntimeException.class)
  public ProblemDetail handleInvalidValueError(RuntimeException ex, HttpServletRequest request)
    throws URISyntaxException {
    
    request.getHeaderNames().asIterator().forEachRemaining(System.out::println);

    ProblemDetail pd = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
    pd.setType(new URI("https://github.com/gwagdalf/problemdetaildemo/blob/main/iiiproblemdetail/README.md"));
    pd.setDetail(ex.getMessage());
    pd.setTitle(HttpStatus.BAD_REQUEST.getReasonPhrase());
    pd.setProperty("timestamp",LocalDateTime.now());
    return pd;
  }
}

https://github.com/gwagdalf/problemdetaildemo/blob/main/iiiproblemdetail/src/main/java/com/example/problemdetail/iiiproblemdetail/errorhandler/AppErrorHandler.java

 

 

 

 

Reference

reference 모음 : https://ride-wind.tistory.com/87