Spring에서 특정 HTTP 응답 상태 반환하기

클라이언트가 서버에 특정 HTTP 요청을 보내면 서버는 HTTP 응답 상태를 반환한다.

클라이언트는 응답 코드를 통해서 서버가 요청 처리를 실패했는지, 거부했는지, 성공했는지 알 수 있다.

Spring 기반 애플리케이션에서 기본 프레임워크는 서버가 반환하는 모든 응답에 적절한 HTTP 응답 상태 코드를 자동으로 추가한다.

또한 Spring은 컨트롤러의 HTTP 응답 상태를 사용자 정의하는 방법도 제공한다.

 

HTTP Response Status Code

• 1xx : 1로 시작하는 모든 상태 코드는 정보 코드이다.
• 2xx : 요청이 성공적으로 완료되었음을 나타낸다.
• 3xx : 리다이렉션을 나타낸다. 요청을 처리하기 위해 추가 조치가 필요하다.
• 4xx : 요청이 유효하지 않거나 완료할 수 없어 요청에 실패했다.
• 5xx : 요청이 유효하지만 서버에 문제가 있어 서버가 요청을 처리할 수 없다.

Spring 컨트롤러는 각 응답에 적절한 상태 코드를 자동으로 포함한다. 

요청 처리가 예외 없이 완료되면 200을 반환하고, 요청에 포함된 리소스를 찾을 수 없으면 404를 반환하며, 서버에 예외가 발생하면 500을 반환한다.

 

이러한 자동 응답 코드를 사용자 정의하거나 클라이언트가 기대하는 보다 구체적인 상태 코드를 반환하고 싶을 때가 있다.

Spring은 HTTP 응답 상태 코드를 사용자 정의 할 수 있는 다음과 같은 방법을 제공한다.

• ResponseEntity 객체 응답
• @ResponseStatus 어노테이션
• ResponseStatusException 예외 발생

 

ResponseEntity 객체 응답

ResponseEntity 인스턴스와 함께 HTTP 응답 상태 코드를 전송할 수 있다.

@PostMapping("/students")
public Student postStudent(@RequestBody Student student) {
    log.info("Request to create sutdent: {}", student);
    return service.addNewStudent(student);
}

요청을 통해서 전달 받은 Student 인스턴스를 생성하는 API가 있다.

API를 호출했을 때 성공적으로 수행했을 때 Spring에서는 200 응답 코드를 보낸다.

요청을 통해서 전달 받은 Student 인스턴스를 생성하는 API에서 성공적으로 처리가 완료되면 201(CREATED) 응답을 보내고 싶을 때 ResponseEntity 객체를 통해서 다음과 같이 API를 작성할 수 있다.

@PostMapping("/students")
public ResponseEntity<Student> postStudent(@RequestBody Student student) {
    log.info("Request to create student: {}", student); 
    Student newStudent = service.addNewStudent(student);
    return new ResponseEntity<>(student, HttpStatus.CREATED);
}

HTTP POST /students API를 호출하면 컨트롤러는 201 응답 코드를 반환한다.

HTTP 응답 상태 코드 201은 서버에서 리소스가 생성되었음을 나타낸다.

 

@ResponseStatus 어노테이션

@ResponseStatus 어노테이션은

• 컨트롤러나 예외 핸들러 메서드에 사용할 수 있다.
• 예외 클래스에서 사용할 수 있다.

예외 클래스에서 @ResponseStatus 사용

Spring 애플리케이션에서 사용자 지정 예외를 생성할 때 예외를 특정 응답 상태 및 선택적 오류 메시지와 연결할 수 있다.

@ResponseStatus(
    value = HttpStatus.NOT_FOUND, 
    reason = "Requested student does not exist"
)
public class StudentNotFoundException 
    extends RuntimeException {
 
  public StudentNotFoundException(Throwable t) {
    super(t);
  }
}

컨트롤러에서 StudentNotFoundException이 발생하면 Spring은 지정된 HTTP 응답 상태 코드를 자동으로 반환한다.

 

@ExceptionHandler에서 @ResponseStatus 사용

@ExceptionHandler({MyCustomException.class})
@ResponseStatus(
    value = HttpStatus.INTERNAL_SERVER_ERROR, 
    reason = "this is the reason"
)
public void handle() {...}

 

Controller에서 @ResponseStatus 사용

@ResponseStatus 어노테이션이 지정된 컨트롤러 메서드는 응답 페이로드 없이 특정 상태코드만 응답할 수 있다.

@PostMapping("/students")
@ResponseStatus(HttpStatus.CREATED)
public void postStudent(@RequestBody Student student) {
    log.info("Request to create student: {}", student);
    service.addNewStudent(student);
}

 

ResponseStatusException 예외

Spring은 컨트롤러가 특정 상태 코드 및 오류 메시지와 함께 던질 수 있는 ResponseStatusException을 제공한다.

@PostMapping("/students")
public void postStudent(@RequestBody Student student) {
  
    log.info("Request to create student: {}", student);
    try {
        repository.save(student);
    } catch (InvalidStudentException e) {
        throw  new ResponseStatusException(HttpStatus.BAD_REQUEST);
    } catch (StudentServiceException e){
        throw  new ResponseStatusException(HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

정상적으로 동작하는 경우 Spring은 자동으로 200응답 코드를 전송한다.

InvalidStudentException이 발생한 경우에는 BAD_REQUEST 응답 코드를 전송한다.

StudentServiceException이 발생한 경우에는 INTERNAL_SERVER_ERROR 응답 코드를 전송한다.