[트러블 슈팅] ⚠️ @RequestBody로 MultipartFile을 받을 수 없는 이유와 해결법(@RequestPart)

문제 상황

새로운 게시글을 등록할 때, 다음과 같이 DTO로 데이터를 받고 있다.

public class PostCreateRequest {
    private String categoryName;
    private String title;
    private String content;
    private List<MultipartFile> images;
}

이때 컨트롤러에서 해당 DTO를 @RequestBody로 받아 처리하는데, JSON 형식의 데이터만 변환 가능하기 때문에 바이너리 데이터인 MultipartFile은 JSON으로 표현할 수 없어 에러가 발생한다.

---

문제 원인 분석

1. Spring의 @RequestBody는 JSON 형식의 요청 본문만 처리한다.
   • JSON은 텍스트 기반 데이터인데, 파일(MultipartFile)은 바이너리 데이터이므로 JSON으로 변환할 수 없다.
2. Spring에서 JSON으로 자동 변환되는 데이터 타입은 String, Number, Boolean, Array, Object만 지원한다.
   • MultipartFile은 지원되지 않는 데이터 타입이다.
3. HTTP 요청의 Content-Type 충돌 문제가 존재한다.
   • JSON 데이터는 application/json 형태로 전송되어야 한다.
   • 파일 업로드 시 요청은 반드시 multipart/form-data 형태로 전송되어야 한다.

이로 인해 JSON 데이터와 파일 데이터를 동시에 받을 때 충돌이 발생한다.

---

해결 방안

• @ModelAttribute는 multipart/form-data 요청만 처리 가능하며 JSON 요청은 처리할 수 없다.
• @RequestPart를 사용하는 방법으로 해결할 수 있다!
• @RequestPart는 multipart/form-data 형식의 요청 데이터를 받을 수 있다.
• 또한 JSON 데이터도 @RequestBody처럼 자동 매핑할 수 있다.

즉, JSON 데이터와 파일 데이터를 동시에 받아야 할 때는 @RequestPart가 가장 효과적인 해결책이다.

---

최종 결론

게시글 등록처럼 JSON 데이터와 이미지 파일을 동시에 받아야 하는 상황에서는 반드시 @RequestPart를 사용해야 한다!
• JSON 데이터는 DTO로 매핑 가능하다.
• 이미지와 같은 파일 데이터도 문제없이 처리 가능하다.
• 따라서, 요청 데이터 형식이 다른 두 데이터를 동시에 처리하려면 항상 @RequestPart를 선택하면 된다!