Spring @RequestBody로 데이터 바인딩 오류

개요

---

Spring Boot를 사용해 REST API를 개발하면서, 클라이언트로부터 JSON 데이터를 받아 처리하는 상황이 빈번하다. 이때 @RequestBody 애너테이션을 사용해 데이터를 바인딩하는데, 간혹 데이터 형식이 맞지 않거나 잘못된 값이 들어오면 데이터 바인딩 오류가 발생할 수 있다.

 

최근 프로젝트에서도 비슷한 문제가 발생했는데, 이 과정에서 어떻게 오류를 해결하고 예방할 수 있는지에 대해 자세히 알아보게 되었다.

 

@RequestBody와 데이터 바인딩 오류의 이해

---

@RequestBody는 클라이언트로부터 전송된 JSON 데이터를 객체로 변환하는 역할을 한다. 예를 들어, 클라이언트에서 JSON 형식으로 데이터를 보내면, 해당 데이터를 Java 객체로 매핑해 사용할 수 있게 도와준다. 하지만 이 과정에서 JSON 데이터 형식이 Java 객체의 필드와 맞지 않으면 데이터 바인딩 오류가 발생한다.

 

예를 들어, 다음과 같은 코드에서 User 객체로 데이터를 바인딩한다고 가정하자:

public class User {
    private String name;
    private int age;

    // getters and setters
}

 

API 요청을 처리하는 컨트롤러 메서드는 다음과 같이 작성할 수 있다:

@PostMapping("/user")
public ResponseEntity<String> createUser(@RequestBody User user) {
    return ResponseEntity.ok("User created: " + user.getName());
}

 

하지만 클라이언트에서 age 필드에 문자열을 전송하면, Spring은 이 값을 int로 변환할 수 없어서 바인딩 오류가 발생한다.

 

데이터 바인딩 오류 발생 원인

---

주로 다음과 같은 이유로 데이터 바인딩 오류가 발생한다:

• JSON 데이터 형식 불일치: 클라이언트가 잘못된 형식의 데이터를 전송했을 때.
• 필수 필드 누락: 객체의 필수 필드가 JSON 데이터에 포함되지 않았을 때.
• 타입 불일치: 예를 들어, 숫자 필드에 문자열 값이 들어오는 경우.

이러한 문제는 개발자에게는 흔한 일이지만, 클라이언트에서 올바른 데이터를 보내지 않으면 애플리케이션의 안정성에 문제가 생길 수 있다.

 

데이터 바인딩 오류 해결 방법 및 예시 코드

---

유효성 검사 추가하기

Spring에서 @Valid 애너테이션을 사용하면 데이터 바인딩 전에 유효성 검사를 수행할 수 있다. 이를 통해 데이터가 올바른지 미리 검증하고, 검증에 실패하면 적절한 오류 메시지를 클라이언트에 전달할 수 있다. 예를 들어:

import javax.validation.Valid;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;

public class User {
    @NotNull(message = "이름은 필수 입력 항목입니다.")
    private String name;

    @Min(value = 18, message = "나이는 18 이상이어야 합니다.")
    private int age;

    // getters and setters
}

 

컨트롤러에서는 @Valid 애너테이션을 적용하여 요청을 처리한다:

@PostMapping("/user")
public ResponseEntity<String> createUser(@Valid @RequestBody User user, BindingResult result) {
    if (result.hasErrors()) {
        return ResponseEntity.badRequest().body(result.getAllErrors().get(0).getDefaultMessage());
    }
    return ResponseEntity.ok("User created: " + user.getName());
}

 

이렇게 하면 잘못된 데이터가 넘어왔을 때 클라이언트에게 유효성 검증 오류 메시지를 전달할 수 있다.

---

ExceptionHandler를 사용한 오류 처리

데이터 바인딩 오류가 발생할 경우, @ExceptionHandler를 사용하여 전역적으로 오류를 처리할 수도 있다. 이를 통해 보다 명확한 오류 응답을 제공할 수 있다:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<String> handleValidationExceptions(MethodArgumentNotValidException ex) {
        String errorMessage = ex.getBindingResult().getAllErrors().get(0).getDefaultMessage();
        return ResponseEntity.badRequest().body("Validation error: " + errorMessage);
    }
}

 

이렇게 하면 컨트롤러 내에서 예외가 발생하더라도, 전역 예외 처리기를 통해 일관된 방식으로 오류를 응답할 수 있다.

 

정리

---

Spring Boot의 @RequestBody를 사용할 때 데이터 바인딩 오류는 빈번하게 발생할 수 있다. 주된 원인은 JSON 형식 불일치나 필수 필드 누락 등이지만, @Valid 애너테이션을 활용한 유효성 검증과 전역 예외 처리를 통해 문제를 해결할 수 있다.