[Spring] @RequestParam vs @RequestPart 차이점

회원 정보 수정 기능을 구현하던 중 @RequestParam을 사용해 데이터를 받으려고 했는데, 이미지 업로드와 JSON 데이터를 함께 처리할 때 문제가 발생했다.

원인을 찾아보니, 파일이나 JSON처럼 복합적인 데이터 타입을 처리할 때는 @RequestParam이 아닌 @RequestPart를 사용해야 한다는 걸 알게 됐다.
이 경험을 계기로 이번 글에서는 @RequestParam과 @RequestPart의 차이와 각각 언제 사용해야 하는지 정리해보려 한다.

💡 @RequestParam란

: 일반적으로 쿼리 파라미터, 폼 필드 등에서 사용 (ex String, int, boolean..)

• 하나의 파라미터만 받을 때 사용
• 기본적으로 파라미터가 필수값(required = true)으로 설정되어 있어 값이 없으면 예외가 발생!
  • 선택값으로 만들고 싶다면 required = false를 설정해야 함

기본 예시 코드

@GetMapping("/search")
public String search (@RequestParam String name) {
	return "Hello, " + name;
}

호출 예시

GET /search?name=홍길동

• /search 경로로 요청이 들어올 때, 쿼리 파라미터에서 name이라는 값을 가져와서 자동으로 바인딩
• 요청이 들어오면 name 파라미터에 홍길동이 들어가고 반환되어 Hello, 홍길동이 된다.

💡 @RequestPart

: MultipartFile에서 또는 JSON + 파일을 함께 받을 때 사용 (ex DTO, MultipartFile..)

• JSON 형식의 바디와 파일을 받으려면 @RequestPart를 사용
  • 복잡한 값을 처리할 때 사용
• 내부적으로 부분 단위로 데이터를 추출해서 바인딩

DTO + 이미지 파일 예시 코드

@PostMapping("/update")
public String update(
    @RequestPart("data") RequestDto data,
    @RequestPart("image") MultipartFile imageFile
) {
    return "수정 완료: " + data.getName();
}

요청 형태(Postman 기준)

{
  "name": "홍길동",
  "content": "내용입니다"
}

실행 결과

수정 완료: 홍길동

• 이미지는 파일로, 수정 정보는 JSON 형식의 DTO로 전달되기 때문에 서로 다른 형식의 데이터를 받기 위해서는 @RequestPart를 사용해야 한다.

💡마무리

작은 문제였지만, 덕분에 @RequestParam과 @RequestPart의 차이를 확실히 이해할 수 있었고, 아직 부족한 점이 많지만, 이런 경험을 통해 조금씩 나아가고 있다고 느낀다!