파일 업로드, 다운로드 (MultipartFile)

📌 1. MultipartFile이란?

MultipartFile은 Spring이 제공하는 파일 업로드를 위한 내장 인터페이스.
multipart/form-data 요청을 처리할 수 있고, 파일 데이터를 다룰 수 있다.

✅ 1-1. MultipartFile 주요 특징

• 스프링이 자동으로 파일을 바인딩해 줌.
• 단일 파일 & 다중 파일 업로드 가능
• @ModelAttribute, @RequestParam과 함께 사용
• 파일 이름, 크기, 확장자, 바이너리 데이터 접근 가능

 

✅ 1-2.  주요 메서드

메서드	설명
getOriginalFilename()	업로드된 파일의 원본 이름 가져오기
getSize()	파일 크기 (바이트 단위)
getContentType()	파일의 MIME 타입 확인
getBytes()	파일을 byte 배열로 변환
getInputStream()	파일을 InputStream으로 가져오기
transferTo(File)	지정된 위치에 파일 저장 (파일 저장 가능)

 

✅ 1-3. MultipartFile 예제

1️⃣ 단일 파일 업로드

요청 예시 (form-data): file: example.jpg

@PostMapping("/upload")
public ResponseEntity<String> uploadFile(@RequestParam("file") MultipartFile file) {
    if (file.isEmpty()) {
        return ResponseEntity.badRequest().body("파일을 선택해주세요.");
    }
    String fileName = file.getOriginalFilename();
    long fileSize = file.getSize();
    return ResponseEntity.ok("파일 업로드 성공! 파일명: " + fileName + ", 크기: " + fileSize + " bytes");
}

 

 

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

요청 예시 (form-data): files: file1.jpg, file2.png, file3.pdf

@PostMapping("/uploadMultiple")
public ResponseEntity<String> uploadMultipleFiles(@RequestParam("files") MultipartFile[] files) {
    for (MultipartFile file : files) {
        if (!file.isEmpty()) {
            System.out.println("파일명: " + file.getOriginalFilename() + " | 크기: " + file.getSize());
        }
    }
    return ResponseEntity.ok("파일 업로드 성공!");
}

 

3️⃣ 파일 저장하기 (transferTo 사용)

@PostMapping("/saveFile")
public ResponseEntity<String> saveFile(@RequestParam("file") MultipartFile file) throws IOException {
    String savePath = "C:/upload/" + file.getOriginalFilename();
    file.transferTo(new File(savePath)); // 파일 저장
    return ResponseEntity.ok("파일이 성공적으로 저장됨: " + savePath);
}

 

 

📌 2. Spring에서 파일 + 데이터 전송 방법

🚨 @RequestBody는 application/json을 사용해야 하지만,
🚨 파일 업로드는 multipart/form-data 방식을 사용해야 해서 동시에 사용할 수 없다!

🔥 JSON과 파일을 같이 보내려면 → @RequestPart 또는 @ModelAttribute 사용!

<form action="/upload" method="post" enctype="multipart/form-data">
    <input type="text" name="username">
    <%-- multiple 속성으로 다중 파일 선택 가능, 허용확장자는 백엔드에서도 관리 --%>
     <input type="file" id="attachFiles" name="attachFiles" accept=".jpg, .jpeg, .png, .gif, .pdf, .zip, .doc, .docx, .xls, .xlsx, .txt" multiple>
    <button type="submit">Upload</button>
</form>

 

✅ 2-1. @ModelAttribute 사용 (폼 데이터 방식)

@ModelAttribute는 폼 데이터 형식 (multipart/form-data) 을 이용해서 객체를 자동 매핑하는 방식이다.

✔ 폼 필드 (title, content 등)와 파일을 함께 보내야 할 때 사용
✔ Postman에서 Form-Data 형식으로 요청해야 함

 

🔹 백엔드 코드 (Spring Controller)

@PostMapping("/insert")
public ResponseEntity<Note> insertNote(
        @ModelAttribute Note note,  
        @RequestParam(value = "attachFiles", required = false) MultipartFile[] attachFiles) {

    Note insertedNote = noteService.insertNote(note, attachFiles);
    return new ResponseEntity<>(insertedNote, HttpStatus.OK);
}

✔  @ModelAttribute Note note → 폼 데이터를 Note 객체로 자동 매핑
✔  @RequestParam MultipartFile[] attachFiles → 파일은 따로 처리

 

🔹 프론트엔드 (JavaScript - FormData 사용)

import axios from "axios";

const handleSubmit = async () => {
    const formData = new FormData();
    formData.append("noteTitl", "테스트 제목");
    formData.append("regtId", 1);
    formData.append("noteCont", "내용입니다.");
   
    // 파일 추가
    const fileInput = document.getElementById("fileUpload");
    if (fileInput.files.length > 0) {
        formData.append("attachFiles", fileInput.files[0]);
    }

    try {
        const response = await axios.post("http://localhost:8080/insert", formData, {
            headers: { "Content-Type": "multipart/form-data" },
        });
        console.log("응답:", response.data);

    } catch (error) {
        console.error("에러 발생:", error);

    }
};

🔹 Postman 요청 설정 (Form-Data 방식)

1. Method: POST
2. Headers: Content-Type: multipart/form-data
3. Body → form-data 선택
4. Key 값 입력 (name은 필드명과 동일해야 함)

Key	Value	Type
noteTitl	test1	Text
regtId	1	Text
noteCont	내용 입력	Text
attachFiles	(파일 선택)	File

 

 

✅ 2-2. @RequestPart 사용 (JSON + 파일 업로드)

✔ JSON 데이터와 파일을 함께 전송해야 할 때 사용
✔ Postman 또는 프론트에서 FormData를 사용해서 JSON + 파일을 같이 전송
✔ @RequestBody 대신 @RequestPart 사용해야 함 (JSON을 multipart/form-data로 처리)

 

🔹 백엔드 코드 (Spring Controller)

@PostMapping(value = "/insert", consumes = { MediaType.MULTIPART_FORM_DATA_VALUE })
public ResponseEntity<Note> insertNote(
        @RequestPart("note") Note note,  // JSON 데이터 받음
        @RequestPart(value = "attachFiles", required = false) MultipartFile[] attachFiles) {

    Note insertedNote = noteService.insertNote(note, attachFiles);
    return new ResponseEntity<>(insertedNote, HttpStatus.OK);
}

 

 

🔹 프론트엔드

import axios from "axios";

const handleUpload = async () => {
    const formData = new FormData();

    // JSON 데이터를 Blob으로 변환하여 추가
    const noteData = {
        "noteTitl": "test1",
        "regtId": 1,
        "noteCont": "123",
        "recipients": [ { "recvUserId": "user1", "recvCcGbn": "CC" }, { "recvUserId": "user2", "recvCcGbn": "BCC" } ]
    };
    
    const noteBlob = new Blob([JSON.stringify(noteData)], { type: "application/json" });
    formData.append("note", noteBlob);

    // 파일 추가
    const fileInput = document.getElementById("fileUpload");
    if (fileInput.files.length > 0) {
        formData.append("attachFiles", fileInput.files[0]);
    }

    try {
        const response = await axios.post("/insert", formData, {
            headers: {
                "Content-Type": "multipart/form-data"
            }
        });

        console.log("업로드 성공:", response.data);
    } catch (error) {
        console.error("업로드 실패:", error);
    }
};

✔  JSON 데이터를 Blob으로 변환 후 FormData에 추가해야 JSON + 파일을 같이 보낼 수 있다!
✔  Content-Type을 따로 지정하지 않아도 자동으로 multipart/form-data로 처리됨

 

📌3. 정리 (어떤 방식이 적절할까?)

방식	@RequestBody	@ModelAttribute	@RequestPart
JSON 데이터만	✅ 가능	❌ 안됨	✅ 가능
폼 데이터만	❌ 안됨	✅ 가능	✅ 가능
JSON + 파일 업로드	❌ 안됨	❌ 안됨	✅ 가능
폼 데이터 + 파일 업로드	❌ 안됨	✅ 가능	✅ 가능

✔  @ModelAttribute → Form-Data 방식으로 폼 데이터 + 파일을 처리
✔  @RequestPart → JSON + 파일 업로드를 처리 (프론트에서 FormData 사용)
✔  @RequestBody + @RequestParam(MultipartFile) → ❌ 함께 사용할 수 없음

 

🎯4. 결론 & 추천

1️⃣ 폼 데이터 방식 (title, content와 파일을 같이 보낼 때)
@ModelAttribute 사용 (폼 데이터 자동 매핑)

2️⃣ JSON + 파일을 같이 보낼 때
@RequestPart 사용 (프론트에서 FormData로 JSON + 파일 전송)

3️⃣ 파일 업로드 단독으로 보낼 때
@RequestParam MultipartFile 사용

 

🔥 파일 + JSON을 같이 보내야 한다면? @RequestPart 추천! 🚀

 

📌 5. 파일 다운로드 예시

@Value("${atchfile.upload.path}")
private String ATCHFILE_UPLOAD_PATH;


   // 첨부 파일 다운로드
   @PostMapping("/download/attachFile.json")
   public ResponseEntity<Resource> getAttachFile(@RequestBody NoteAttachRequestDTO request,
        @RequestHeader(value = "X-User-Name", required = false) String username) {
    try {
    if(!noteRestService.checkNoteAuth(request.getSno(), username)) {
    return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
    }
    NoteAttach file = noteAttachService.getAttachFile(request);
 
    if(file == null){
               return ResponseEntity.notFound().build();
           }  

            Path filePath = Paths.get(ATCHFILE_UPLOAD_PATH + "/" + file.getAtchSaveNm()).toAbsolutePath().normalize();
            Resource resource = new UrlResource(filePath.toUri());
            if (!resource.exists()) {
                return ResponseEntity.notFound().build();
            }
            String originalFileName = file.getAtchNm();
            String encodedFileName = URLEncoder.encode(originalFileName, "UTF-8").replaceAll("\\+", "%20");
            return ResponseEntity.ok()
                    .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + encodedFileName  + "\"")
                    .body(resource);

        } catch (Exception e) {
            e.printStackTrace();
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
        }
   }
 
   // 첨부 파일 전체 다운로드
   @PostMapping("/download/all/attachFile.json")
   public ResponseEntity<Resource> getAllAttachFile(@RequestBody NoteAttachRequestDTO request,
        @RequestHeader(value = "X-User-Name", required = false) String username) {
       try {
    if(!noteRestService.checkNoteAuth(request.getSno(), username)) {
    return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
    }
        List<NoteAttach> atchList = noteAttachService.getAllAttachFile(request.getSno());
           if (atchList == null || atchList.isEmpty()) {
               return ResponseEntity.notFound().build();
           }
           Path zipFilePath = Files.createTempFile(request.getSno() + "_files", ".zip");
           try (ZipOutputStream zipOut = new ZipOutputStream(Files.newOutputStream(zipFilePath))) {
               
               for (NoteAttach file : atchList) {
                   Path filePath = Paths.get(ATCHFILE_UPLOAD_PATH + "/" + file.getAtchSaveNm()).toAbsolutePath().normalize();
                 
                   if (!Files.exists(filePath)) {
                       continue; // 파일이 없으면 건너뜁니다.
                   }
                   
                   // ZIP 파일에 추가
//                    String zipEntryName = file.getAtchNm() + "." + file.getAtchExtn();
                   String zipEntryName = file.getAtchNm();
                   zipOut.putNextEntry(new ZipEntry(zipEntryName));
                   Files.copy(filePath, zipOut);
                   zipOut.closeEntry();

               }
           }
           Resource resource = new UrlResource(zipFilePath.toUri());
           if (!resource.exists()) {
               return ResponseEntity.notFound().build();
           }
           return ResponseEntity.ok()
                   .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=" + request.getSno() + "_files.zip")
                   .contentType(MediaType.APPLICATION_OCTET_STREAM)
                   .body(resource);

       } catch (Exception e) {
           e.printStackTrace();
           return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).build();
       }
   }