API 개발 및 테스트 과정에서 클라이언트가 보내는 데이터 형식과 서버가 받는 방식의 불일치로 인해 발생한 데이터 바인딩 오류일 경우 해결한 방법이다.
📌 1. @ RequestParam
1) 상황
- 에러는 발생하지 않으나 데이터가 null로 들어옴
2) 원인
- @RequestParam은 기본적으로 쿼리스트링(?key=value)이나 HTML Form 데이터(x-www-form-urlencoded)를 받을 때 사용
- Postman에서 JSON 요청(application/json)을 보내면 @RequestParam에서는 값을 받을 수 없음
- 데이터가 Request Body(JSON)에 있었기 때문에 매칭되는 키를 찾지 못해 null이 반환됨
3) 해결방법
- x-www-form-urlencoded 방식 or @RequestBody 사용
- Postman에서 Body → x-www-form-urlencoded 탭 선택
- key=value 형태로 데이터 입력
📌 2. @RequestBody
1) 상황
- Spring이 JSON을 파싱하지 못하고 415 Unsupported Media Type 또는 400 Bad Request 에러 발생
2) 원인
- HttpMessageConverter(주로 Jackson 라이브러리)를 통해 Request Body에 담긴 데이터(JSON, XML 등)를 Java 객체로 역직렬화(Deserialization)함
- 요청 헤더의 Content-Type이 application/json으로 명시되지 않았거나, JSON 데이터 형식이 Java 객체(DTO) 구조와 맞지 않아 파싱에 실패
3) 해결방법
- ✅ Case 1: Form 데이터(x-www-form-urlencoded)로 보낼 때
- Server (Spring): @RequestParam 또는 @ModelAttribute 사용
- Client (Postman): Body 탭 → x-www-form-urlencoded 선택 → Key-Value 입력
- ✅ Case 2: JSON 데이터(application/json)로 보낼 때
- Server (Spring): @RequestBody 사용
- Client (Postman): Body 탭 → raw 선택 → JSON 포맷 선택 (헤더에 Content-Type: application/json 자동 포함됨)
💡정리
API 통신 시 단순히 데이터만 보내는 것이 아니라, 헤더의 Content-Type이 서버가 기대하는 어노테이션(@RequestBody vs @RequestParam)과 일치하는지 반드시 확인해야 하고, Request Header와 Body가 어떤 형태로 전송되고 있는지 먼저 확인해야 한다. @RequestParam을 사용하면 에러는 안 나지만 값이 들어오지 않았고, @RequestBody를 사용하면 Spring이 JSON을 파싱하지 못해서 에러가 발생했는데, 결국 근본적인 원인은 클라이언트가 전송하는 데이터 형식(Content-Type)과 서버가 데이터를 수신하는 방식(Annotation)이 서로 엇갈렸기 때문이다. 이를 통해 JSON 데이터를 전송할 때는 단순히 Body에 값을 넣는 것을 넘어, 헤더에 application/json을 명시하고 @RequestBody를 통해 객체로 매핑해야 한다는 메커니즘을 명확히 이해하고 해결할 수 있었다.
댓글