[spring boot] MultipartFile이란?

Java/Spring Boot

[spring boot] MultipartFile이란?

너무 궁금해 2025. 2. 27. 11:18

📌 MultipartFile이란?

MultipartFile은 Spring Framework에서 제공하는 인터페이스로, HTTP 요청을 통해 업로드된 파일을 다룰 때 사용됩니다. multipart/form-data 타입의 요청을 처리할 수 있도록 설계되어 있으며, 이를 활용하면 이미지, 문서 등 다양한 파일을 서버로 업로드할 수 있습니다.

1️⃣ MultipartFile 기본 개념

Spring에서는 클라이언트가 파일을 업로드할 때 multipart/form-data 형식으로 요청을 보내야 합니다. 이때 Spring의 MultipartResolver가 요청을 해석하고, MultipartFile 객체를 생성하여 컨트롤러에서 이를 받을 수 있도록 합니다.

✅ MultipartFile 인터페이스 주요 메서드

메서드	설명
getName()	요청 파라미터의 이름 반환
getOriginalFilename()	업로드된 파일의 원본 이름 반환
getContentType()	파일의 MIME 타입 반환 (image/png, application/pdf 등)
getSize()	파일 크기(byte 단위) 반환
isEmpty()	파일이 비어있는지 확인
getBytes()	파일을 바이트 배열로 변환
getInputStream()	파일을 스트림 형태로 변환
transferTo(File dest)	파일을 지정한 위치로 저장

2️⃣ 하나의 파일 업로드 예제 (Spring Boot)

Spring Boot에서 MultipartFile을 이용하여 파일을 업로드하는 예제를 만들어 보겠습니다.

import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.IOException;

@RestController
@RequestMapping("/upload")
public class FileUploadController {

    @PostMapping
    public String uploadFile(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return "파일이 비어 있습니다.";
        }

        // 파일 저장 경로 (예제: 로컬 디렉토리)
        String filePath = "C:/upload/" + file.getOriginalFilename();

        try {
            file.transferTo(new File(filePath)); // 파일 저장
            return "파일 업로드 성공: " + file.getOriginalFilename();
        } catch (Exception e) {
            return "파일 업로드 실패: " + e.getMessage();
        }
    }
}

📝 파일 업로드 테스트 (Postman)

위의 컨트롤러를 실행한 후 Postman을 사용하여 파일 업로드를 테스트할 수 있습니다.

Postman 실행
POST 요청을 보낼 URL: http://localhost:8080/upload
Body → form-data 선택
key 값을 file로 설정 (컨트롤러에서 @RequestParam("file")로 받으므로)
Type을 File로 선택 후 업로드할 파일 추가
Send 버튼 클릭 → 응답 확인

💡 첨부파일 앞에 느낌표가 있다면 Working Directory를 설정해야 합니다.

🔧 Postman의 작업 디렉토리 설정 변경

Postman 실행
Settings(설정) → General(일반) 탭으로 이동
Working Directory(작업 디렉토리) 항목 찾기
"Change Directory"(디렉토리 변경) 버튼 클릭
업로드할 파일이 있는 폴더를 선택하여 작업 디렉토리로 설정
설정 저장 후 Postman 재시작

👉 이렇게 하면 Postman이 해당 폴더 내 파일을 정상적으로 참조할 수 있습니다. (느낌표시가 사라짐~)

👉 Send 버튼을 누르면 정상적으로 파일이 업로드됩니다.

3️⃣ 여러 개의 파일 업로드

파일을 여러 개 업로드하고 싶다면 List<MultipartFile>을 사용하면 됩니다.

import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.io.File;
import java.io.IOException;
import java.util.List;

@RestController
@RequestMapping("/multiple")
public class MultiFileUploadController {

    @PostMapping
    public String uploadMultipleFiles(@RequestParam("files") List<MultipartFile> files) {
        if (files.isEmpty()) {
            return "파일이 없습니다.";
        }

        String uploadPath = "C:/upload/";
        StringBuilder responseMessage = new StringBuilder();

        for (MultipartFile file : files) {
            try {
                file.transferTo(new File(uploadPath + file.getOriginalFilename()));
                responseMessage.append("파일 업로드 성공: ").append(file.getOriginalFilename()).append("\n");
            } catch (IOException e) {
                responseMessage.append("파일 업로드 실패: ").append(file.getOriginalFilename()).append("\n");
            }
        }
        return responseMessage.toString();
    }
}

✔ @RequestParam("files") List<MultipartFile> files를 사용하여 여러 개의 파일을 받습니다.
✔ 반복문을 사용하여 각 파일을 저장합니다.

🔧 Postman 테스트 방법

POST 요청을 보낼 URL: http://localhost:8080/upload/multiple
Body → form-data 선택
key 값을 files로 설정
Type을 File로 선택 후 여러 개의 파일 추가
Send 버튼 클릭 → 응답 확인

👉 테스트 결과입니다.

4️⃣ 파일 크기 제한

application.properties파일에서 업로드할 파일 크기를 설정할 수 있습니다.

spring.servlet.multipart.enabled=true
spring.servlet.multipart.max-file-size=5MB      # 개별 파일 크기 제한
spring.servlet.multipart.max-request-size=20MB  # 전체 요청 크기 제한

5️⃣ 업로드 파일 확장자 제한 (예: 이미지만 허용)

파일 확장자를 검사하여 특정 유형의 파일만 업로드하도록 설정할 수도 있습니다.

@RestController
@RequestMapping("/limit")
public class LimitUploadController {

    @PostMapping
    public String limitUpload(@RequestParam("file") MultipartFile file) {
        if (file.isEmpty()) {
            return "파일이 없습니다.";
        }

        // 허용할 확장자 목록
        List<String> allowedExtensions = List.of("jpg", "jpeg", "png", "gif");

        // 파일 확장자 추출
        String originalFilename = file.getOriginalFilename();
        assert originalFilename != null;
        String fileExtension = originalFilename.substring(originalFilename.lastIndexOf(".") + 1);

        if (!allowedExtensions.contains(fileExtension.toLowerCase())) {
            return "허용되지 않은 파일 형식입니다.";
        }

        try {
            file.transferTo(new File("C:/upload/" + originalFilename));
            return "파일 업로드 성공: " + originalFilename;
        } catch (IOException e) {
            return "파일 업로드 실패: " + e.getMessage();
        }
    }
}

-- 끝 --