개발/Java

@ParameterObject vs @RequestBody 차이점 정리

뇽.뇽 2025. 5. 16. 17:44
반응형
반응형

 

스프링(Spring)에서 백엔드 API를 개발할 때, 프론트엔드(Angular)와 통신하는 방식에 따라 데이터를 받는 방법이 달라집니다. 특히 파일 업로드, 복잡한 객체 전달처럼 POST, PUT 요청이 필요한 경우에는 @RequestBody를 써야 하고, 단순 필터링/쿼리 조회 같은 GET 요청에서는 @ParameterObject를 사용하는 게 적절합니다.

최근 제가 겪은 실제 문제를 예시로 사용하면서 개념을 함께 정리해보겠습니다.

문제 상황: @ParameterObject로는 파일을 받을 수 없었던 이유

상황 설명

Angular에서 POST 방식으로 서버에 데이터를 보낼 때, JSON 객체 안에 파일 리스트(FileList)를 함께 전송했습니다.

const formData = new FormData();
formData.append('title', this.form.value.title);
formData.append('file', this.selectedFile); // File 객체 포함

this.http.post('/api/upload', formData).subscribe();

 

서버에서는 아래처럼 @ParameterObject로 받았는데, 파일이 null로 들어왔습니다.

@PostMapping("/upload")
public void uploadFile(@ParameterObject MyUploadDto dto) {
    // dto.getFile() -> null
}

 

원인

@ParameterObject는 GET 방식의 요청 파라미터(query string)에서 값을 매핑할 때 사용하는 어노테이션입니다.
FormData, JSON, 파일 전송 등은 Body 영역에 담겨 전송되므로 @RequestBody를 사용해야 합니다.

 

해결 방법

@PostMapping("/upload")
public void uploadFile(@RequestBody MyUploadDto dto) {
    // 정상적으로 File 리스트 포함 데이터 수신 가능
}

 

단, 파일 업로드는 일반적으로 MultipartFile을 쓰는 것이 권장되므로, 실제로는 아래처럼 받는 것이 좋습니다.

@PostMapping("/upload")
public void uploadFile(@RequestParam("title") String title,
                       @RequestPart("file") MultipartFile file) {
    // file 처리
}

 

어노테이션별 사용 정리

어노테이션 용도 요청 방식 예시

@PathVariable URL 경로에서 값을 추출할 때 GET, DELETE /api/users/{id}
@RequestParam 단일 쿼리 파라미터 받을 때 GET, POST /api/search?keyword=abc
@ParameterObject 여러 쿼리 파라미터를 객체로 받을 때 GET /api/search?name=kim&age=30
@RequestBody JSON 객체를 body로 받을 때 POST, PUT 등 Angular에서 http.post(..., body)
@RequestPart Multipart 요청 시 개별 파트 POST (파일 업로드 등) FormData, file upload

 

주의할 점

  • @ParameterObject는 내부적으로 @ModelAttribute처럼 동작합니다. 따라서 Body 데이터를 파싱하지 않습니다.
  • FormData를 사용할 경우 스프링에서는 @RequestBody가 아니라 @RequestPart 또는 @RequestParam으로 처리해야 합니다.
  • @RequestBody는 파일 업로드와 호환되지 않기 때문에, JSON + 파일을 함께 보내는 경우에는 @RequestPart + DTO 분리로 처리해야 합니다.

마무리 정리

Angular와 Spring 통신 시 데이터 전달 방식에 따라 적절한 어노테이션을 사용하지 않으면 파일이 null로 들어오거나, 객체가 비어있는 현상이 발생할 수 있습니다.

 

상황 사용 방식

URL에서 값 가져오기 @PathVariable
GET 요청, 다수 파라미터 @ParameterObject ← Angular에서는 params로 전달
POST/PUT 요청, JSON 데이터 @RequestBody ← Angular에서는 body로 전달
파일 업로드 @RequestParam or @RequestPart ← Angular는 FormData 사용

 

반응형