Spring 파일 업로드, 다운로드

참고로 백엔드에서 파일을 업로드/다운로드 할 때,

데이터베이스에는 파일 경로 (보통 기본 root를 제외한 상세 경로)를 저장해두고

파일은 다른 경로에 따로 저장하거나, 별도의 컨텐츠용 서버에 관리한다.

글 마지막에 실제 코드는 어떻게 만들 수 있는지 설명하도록 하겠다.

 

 

# HTTP에서는 어떻게 데이터를 주고받는가

HTTP에서 텍스트 데이터를 Body에 넣어 전송할 때 사용하는 가장 기본적인 방법은 POST - Form 방식이다.

폼을 전송할 때 HTTP 헤더에 content-type = application/x-www-form-urlencoded로 지정하면 아래와 같이 동작한다. 

 ➡ 이 방식은 모든 메시지를 String으로 처리해서 전송한다. 

HTTP 메시지는 Header나 Body나 결국 텍스트로 이루어진 데이터이다.

 

@ HTTP에서 처리해준다는게 무슨 의미죠?

웹 브라우저는 HTTP 표준 스펙(인터페이스)를 구현한 프로그램이다. 즉 HTTP에 적혀있는 기능은 웹 브라우저가 구현하고 우리가 사용할 수 있게 HTTP 인터페이스를 제공해준다.

 

요즘은 웹 브라우저 말고도 다양한 곳에서 HTTP를 이용해 데이터를 주고 받는다. 이는 클라이언트 ,서버가 HTTP 스펙을 구현하고 HTTP 인터페이스를 사용할 수 있게 기능을 제공해주기 때문이다.

 

---

# HTTP의 Content-type 헤더

HTTP에서 사용하는 Content-type 헤더는 [HTTP Message Body]에 들어가는 데이터 타입을 명시한다.

Content-type에는 MIME(Multipurpose Internet Mail Extensions) 에 명시된 타입 중 하나를 사용하여 메시지를 인코딩한다. 그 중 데이터를 전송할 때 사용하는 대표적인 타입이 multipart(여러파일과 폼을 함께 전송하는 방식) 이다.

• multipart/mixed : 어떤 데이터가 첨부된 텍스트 메시지
• multipart/alternative : 대체할 수 있는 데이터 타입을 함께 보낸 메시지 (text + HTML 등)
• multipart/form-data : 특수한 문법으로 여러 데이터를 함께 전송한다.

 

@ multipart/form-data

보통 데이터를 전송할 때에는 content-type =  multipart/form-data 를 많이 사용한다.

이를 이용하면 서로 다른 형식의 데이터 (이미지, 영상, HTML Form)을 한번에 묶어서 전송할 수 있다.
 ➡ 참고로 이 방식을 사용하려면 enctype = "multipart/form-data"도 같이 지정해줘야 한다.

이미지, 사진 같은 이진 데이터도 결국 2진수로 이루어진 값이다. HTTP body에 담아 보낼 수 있다.

 

multipart/form-data는 구분자(boundary)를 이용해서 여러가지 타입의 데이터를 파트별로 구분한다. 

실제 생성된 HTTP Reqeust, Response 메시지

클라이언트에서 test.txt, number.txt 파일을 전송하는 경우

Content-Type: multipart/form-data; boundary=Uee--r1_eDOWu7FpA0LJdLwCMLJQapQGu

## HTTP Request Data

POST /file/upload HTTP/1.1[\r][\n]
Content-Length: 344[\r][\n]
Content-Type: multipart/form-data; boundary=Uee--r1_eDOWu7FpA0LJdLwCMLJQapQGu[\r][\n]
Host: localhost:8080[\r][\n]
Connection: Keep-Alive[\r][\n]
User-Agent: Apache-HttpClient/4.3.4 (java 1.5)[\r][\n]
Accept-Encoding: gzip,deflate[\r][\n]

[\r][\n]
--Uee--r1_eDOWu7FpA0LJdLwCMLJQapQGu[\r][\n]
Content-Disposition: form-data; name=files; filename=test.txt[\r][\n]
Content-Type: application/octet-stream[\r][\n]

[\r][\n]
aaaa데이터데이터데이터( 파일명은 test.txt이에요. )이건 데이터

[\r][\n]
--Uee--r1_eDOWu7FpA0LJdLwCMLJQapQGu[\r][\n]
Content-Disposition: form-data; name=files; filename=number.txt[\r][\n]
Content-Type: application/octet-stream[\r][\n]

[\r][\n]
111123154251252 (파일명은 number.txt이에요) 12412904

[\r][\n]
--Uee--r1_eDOWu7FpA0LJdLwCMLJQapQGu--[\r][\n]

 

서버에서 HTTP 200응답이 온 경우

## HTTP Response Data

HTTPHTTP/1.1 200 OK[\r][\n]
Server: Apache-Coyote/1.1[\r][\n]
Accept-Charset: big5, big5-hkscs, euc-jp, euc-kr...[\r][\n]
Content-Type: text/html;charset=UTF-8[\r][\n]
Content-Length: 7[\r][\n]
Date: Mon, 30 Jun 2014 01:28:19 GMT[\r][\n]

[\r][\n]

SUCCESS

 

 

---

# 서블릿에서의 파일업로드

🧨 이 내용은 실제로 사용하지는 않는 기능이다. 맘편하게 읽어보자

간단하다. HttpServletRequest에 있는 getParts()를 이용하면 된다. 이는 서블릿 스펙 3.0부터 제공하는 기능이다.

@PostMapping("/upload")
public String saveFileV1(HttpServletRequest request) throws
    ServletException, IOException {

    // request.getParts() 를 이용하면, multipart/form-data 방식으로 데이터를 받을 수 있다.
    // 이는 Part 객체로 나누어져서 전송된다.
    Collection<Part> parts = request.getParts(); // import javax.servlet.http.Part;

    return "upload-form";
}

참고로 해당 로그는 logging.level.org.apache.coyote.http11=debug 로 해야 확인할 수 있다.

위에 말한 multi-part 방식으로, 이미지파일(이진파일)을 전송받고 있다.

 

서블릿에서는 HttpRequest 객체를 사용하면, 이를 상속한 RequestFacade를 통해 멀티파트 데이터를 처리해준다.

하지만 스프링에서는 이를 사용하지 않는다. 해당 기능을 Off 시켜놓고, 따로 스프링 전용 객체로 추상화 시켜놓았다.

만약 서블릿 컨테이너에서 제공하는 멀티파트 설정을 사용하고 싶다면, 아래와 같이 변경할 수 있다.
물론 spring.multipart.enabled = false로 해버리면, 스프링 Controller에서 사용하기 번거로워진다.

spring.servlet.multipart.max-file-size= 1MB // 기본값, 파일 하나의 max size
spring.servlet.multipart.max-request-size= 10MB // 기본값, 한 요청의 전체파일 max size

/*
multipart는 일반적인 요청보다 처리과정이 매우 복잡하다.
그래서 서블릿 컨테이너에서 멀티파트 처리를 Off 해놓고, 스프링에서 관련된 처리를 따로 한다.
만약 서블릿에서 처리하도록 만들고 싶다면 multipart.enabled= false로 설정해주면 된다.
*/
spring.servlet.multipart.enabled= true // 기본값

참고로 스프링은 디스패쳐 서블릿에서 MultipartResolver를 통해 적절한 HttpServletRequest 구현체로 변경해서 사용한다.

기본 구현체는 StandardMultipartHttpServeltRequest이며 이를 통해 멀티파트 값을 처리해준다.

 

물론 사용하기 편하게 추상화한것일 뿐, 결국 최종적으로는 서블릿으로 파일을 전송받는건 동일하다.

이 과정은 DispatcherServlet.doDispatcher() 의 구현코드를 보면 쉽게 이해할 수 있다.

서블릿 컨테이너(톰캣)에서 받은 HttpRequest 객체를 아래와 같이 설정해준다.

protected void doDispatch(HttpServletRequest request, HttpServletResponse response) throws Exception {
    HttpServletRequest processedRequest = request;
    HandlerExecutionChain mappedHandler = null;
    boolean multipartRequestParsed = false;

    WebAsyncManager asyncManager = WebAsyncUtils.getAsyncManager(request);

    try {
        ModelAndView mv = null;
        Exception dispatchException = null;

        try {
            // Multipart 형태의 요청이라면 HttpRequest 구현체를 바꿔준다.
            processedRequest = checkMultipart(request); // 해당 메서드 내부에서 multipartResolver 사용
            multipartRequestParsed = (processedRequest != request);

            // Determine handler for the current request.
            mappedHandler = getHandler(processedRequest);
            if (mappedHandler == null) {
                noHandlerFound(processedRequest, response);
                return;
            }
... 이하 코드 생략 ...

 

 

 

📌 파일 업로드 해보기

1. multipart 형식으로 POST 요청을 할 수 있는 페이지를 만든다.

HTML의 <input type="file"> 태그를 이용하면 손쉽게 만들 수 있다.

 

2. 서버에 파일이 업로드될 경로를 지정한다.

# application.properties
file.dir = /Users/jiwon/my/files # 원하는 경로를 설정한다.

@Controller
@RequestMapping("/servlet/v2")
public class ServletUploadControllerV2 {
     @Value("${file.dir}")
     private String fileDir; // 물론 그냥 String 으로 경로를 박아넣는 방법도 있다.
}

 

3. HttpServletRequest.getParts() 를 통해 Collection<Part>객체를 통해 멀티파트 데이터를 받는다.

@GetMapping("/upload") // 파일 업로드 페이지 제공
    public String getUploadForm() {
        return "upload-form";
    }

@PostMapping("/upload") 
public String uploadFile(HttpServletRequest request) throws
    ServletException, IOException {

    String itemName = request.getParameter("itemName");
    Collection<Part> parts = request.getParts();

    for (Part part : parts) {
        // 각 Part 의 이름
        log.info("name={}", part.getName());

        // 각 Part 의 헤더값
        Collection<String> headerNames = part.getHeaderNames();
        for (String headerName : headerNames) {
            log.info("header {}: {}", headerName, part.getHeader(headerName));
        }
        // 각 Part 의 편의 메서드 (size, FileName 등)
        //content-disposition; filename
        log.info("submittedFileName={}", part.getSubmittedFileName());
        log.info("size={}", part.getSize()); //part body size

        // 각 Part 의 데이터 바디
        InputStream inputStream = part.getInputStream();
        String body = StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8);
        log.info("body={}", body);

        // Part 에서 꺼낸 데이터를 내가 원하는 파일로 저장하기
        if (StringUtils.hasText(part.getSubmittedFileName())) {
            String fullPath = fileDir + part.getSubmittedFileName();
            log.info("파일 저장 fullPath={}", fullPath);
            part.write(fullPath);
        }
    }

    return "upload-form"; // 파일 업로드 완료후, 다시 GET 페이지로
}

 

직접 해보면 알겠지만, 이렇게 하나하나 처리하는건 매우 번거롭다.

 

 

📌 스프링에서 파일처리, MultipartFile 인터페이스

스프링에서는 MultipartFile 인터페이스를 사용하면 파일처리를 매우 쉽게 할 수 있다.

딱히 설명이 필요없다. @RequestParam 으로 HTML Form 이름을 받거나, DTO에 담아 @ModelAttribute를 써도 된다.

@PostMapping("/upload")
public String uploadFile(@RequestParam MultipartFile file) throws IOException {
    // 업로드하는 HTML Form 이름(file)에 맞춰서 사용하면 된다. 이름을 모른다면 @ModelAttribute 로 받을 수도 있다.

    log.info("multipartFile={}", file);

    if (!file.isEmpty()) {
        String fullPath = fileDir + file.getOriginalFilename();

        log.info("파일 저장 fullPath={}", fullPath);
        file.transferTo(new File(fullPath)); // java.io.File 로 변환
    }

    return "upload-form";
}

참고로 Java.io.File 객체는 아래와 같이 사용할 수 있다.

---

📌 복잡한 파일업로드 예제

1. 도메인 구현

예를 들어, 쇼핑몰 판매자 페이지가 있고

[상품 이름] [첨부파일 1개] [이미지 파일 여러개]를 한번에 업로드 해야한다고 가정해보자.

@Data /* Item 도메인 구현 */
public class Item {
    private Long id;
    private String itemName; // 상품 이름
    private UploadFile attachFile; // 첨부파일 1개
    private List<UploadFile> imageFiles; // 이미지파일 여러개
}

@Repository
public class ItemRepository {

    private final Map<Long, Item> store = new HashMap<>();
    private long sequence = 0L;

    public Item save(Item item) {
        item.setId(++sequence);
        store.put(item.getId(), item);
        return item;
    }

    public Item findById(Long id) {
        return store.get(id);
    }
}

 

참고로 파일명을 String으로 관리해도 되지만, 관리하기 편하게 UploadFile 객체를 추가적으로 만들었다.

@Data
public class UploadFile {

    private String uploadFileName; // 고객이 업로드한 파일 명
    private String storeFileName; // 서버에 저장되는 파일 명 (파일이름이 겹치지않게 처리)

    public UploadFile(String uploadFileName, String storeFileName) {
        this.uploadFileName = uploadFileName;
        this.storeFileName = storeFileName;
    }
}

 

2. 파일을 서버에 저장할 FileStore 객체 구현

컨트롤러에서 MultiPart 데이터를 직접 저장해도 되지만, 책임을 분리하여 FileStore 객체를 따로 만들자.

@Component
public class FileStore {

    @Value("${file.dir}")
    private String fileDir;

    // 파일 저장
    public UploadFile storeFile(MultipartFile file) throws IOException {
        if (file.isEmpty()) {
            return null;
        }
        String originalFilename = file.getOriginalFilename();
        String storeFileName = createStoreFileName(originalFilename);
        file.transferTo(new File(getFullPath(storeFileName)));
        
        // 저장된 UploadFile 이름을 만들어 반환
        return new UploadFile(originalFilename, storeFileName);
    }


    // storFile을 이용한 파일 여러 개 저장
    public List<UploadFile> storeFiles(List<MultipartFile> files)
        throws IOException {
        List<UploadFile> storeFileResult = new ArrayList<>();
        for (MultipartFile multipartFile : imageFiles) {
            if (!imageFile.isEmpty()) {
                storeFileResult.add(storeFile(multipartFile));
            }
        }
        return storeFileResult;
    }
    
    // 저장할 경로 지정
    private String getFullPath(String filename) {
        return fileDir + filename;
    }
    
    // 서버에 저장할 고유한 파일명 생성
    private String createStoreFileName(String originalFilename) {
        String ext = extractExt(originalFilename); // 파일명에서 확장자를 추출
        String uuid = UUID.randomUUID().toString();
        return uuid + "." + ext;
    }

    private String extractExt(String originalFilename) {
        int pos = originalFilename.lastIndexOf(".");
        return originalFilename.substring(pos + 1);
    }
}

 

 

3. 컨트롤러 구현

FileStore를 별도로 만들었으므로, 컨트롤러는 구현은 간단하다. 그냥 MultipartFile을 받아서 전달해주면 끝이다.

@Data // Item_Upload_Request (DTO)
public class ItemForm {
    private Long itemId;
    private String itemName;
    private List<MultipartFile> imageFiles;
    private MultipartFile attachFile;
}

@Controller
@RequiredArgsConstructor
public class ItemController {

    private final ItemRepository itemRepository;
    private final FileStore fileStore;
    
    ...
}

 

컨트롤러에서 사용할 파일업로드/다운로드 HTML 폼을 만들어주자.

참고로 <input>으로 여러개의 파일을 등록하고 싶다면, <input type="file" multiple="multiple"> 로 설정할 수 있다.
이는 스프링 컨테이너에서 List<MultipartFile> files 로 쉽게 받을 수 있다.

<!DOCTYPE HTML> <!-- uploadForm.HTML -->
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
</head>
<body>
<div class="container">
  <div class="py-5 text-center">
    <h2>상품 등록</h2>
  </div>
  <form enctype="multipart/form-data" method="post" th:action>
    <ul>
      <li>상품명 <input name="itemName" type="text"></li>
      <li>첨부파일<input name="attachFile" type="file"></li>
      <li>이미지 파일들<input multiple="multiple" name="imageFiles"
                        type="file"></li>
    </ul>
    <input type="submit"/>
  </form>
</div> <!-- /container -->
</body>
</html>

<!DOCTYPE HTML> <!-- upload-view.HTML -->
<html xmlns:th="http://www.thymeleaf.org">
<head>
  <meta charset="utf-8">
</head>
<body>
<div class="container">
  <div class="py-5 text-center">
    <h2>상품 조회</h2>
  </div>
  상품명: <span th:text="${item.itemName}">상품명</span>
  <br/>
  첨부파일: <a th:href="|/attach/${item.id}|" 
           th:if="${item.attachFile}"
           th:text="${item.getAttachFile().getUploadFileName()}"/>
  <br/>
  <img height="300" 
       th:each="imageFile : ${item.imageFiles}" 
       th:src="|/images/${imageFile.getStoreFileName()}|" width="300"/>
</div> <!-- /container -->
</body>
</html>

 

 

그리고 아래와 같은 API를 제공해주면 된다.

• Get ("/items/new") - 업로드용 폼을 제공해준다.

    @GetMapping("/items/new")
    public String newItem(@ModelAttribute ItemForm form) {
        return "item-form";
    }

 

• Post ("/items/new") - 폼 데이터를 받아서 서버에 저장하고, 업로드 화면으로 리다이렉트 시킨다.

@PostMapping("/items/new")
public String saveItem(@ModelAttribute ItemForm form, RedirectAttributes redirectAttributes) 
throws IOException {

    // 서버에 파일 저장
    UploadFile attachFile = fileStore.storeFile(form.getAttachFile());
    List<UploadFile> storeImageFiles = fileStore.storeFiles(form.getImageFiles());

    // 데이터베이스에 Item 도메인 저장
    Item item = new Item();
    item.setItemName(form.getItemName());
    item.setAttachFile(attachFile);
    item.setImageFiles(storeImageFiles);
    itemRepository.save(item);

    // 리다이렉트 (POST -> GET)
    redirectAttributes.addAttribute("itemId", item.getId());
    return "redirect:/items/{itemId}";
}

 

• Get ("/items/{ id }") - 저장된 상품을 보여준다

@GetMapping("/items/{id}")
public String items(@PathVariable Long id, Model model) {
    Item item = itemRepository.findById(id);
    model.addAttribute("item", item);
    
    return "item-view";
}

 

• Get ("/imags/{ filename }") - <img> 태그로 이미지를 조회할 때 사용한다. 이미지 바이너리를 반환한다.
  이는 스프링이 제공해주는 UrlResource 객체를 이용하면 파일을 쉽게 반환할 수 있다.

@ResponseBody // 바이너리를 직접 HTTP Body로 반환할거라, @ResponseBody 사용
@GetMapping("/images/{filename}")
public Resource downloadImage(@PathVariable String filename) throws MalformedURLException {
    return new UrlResource("file:" + fileStore.getFullPath(filename));
}

 

• Get ("/attach/{ itemId }") - 첨부파일을 다운로드 한다. 클라이언트가 다운 파일명을 정하도록 만드는게 좋다.

@GetMapping("/attach/{itemId}")
public ResponseEntity<Resource> downloadAttach(@PathVariable Long itemId) throws MalformedURLException {
    Item item = itemRepository.findById(itemId);
    
    // HTTP content-disposition Header 설정, 브라우저에서 해당 데이터를 다운로드함
    // ex) Content-Disposition: attachment; filename="hello.jpg"
    String uploadFileName = item.getAttachFile().getUploadFileName();
    String encodedUploadFileName = UriUtils.encode(uploadFileName, StandardCharsets.UTF_8);
    String contentDisposition = "attachment; filename=\"" + encodedUploadFileName + "\"";

    // 파일 경로를 찾아서 UrlResource 생성
    String storeFileName = item.getAttachFile().getStoreFileName();
    UrlResource resource = new UrlResource("file:" + fileStore.getFullPath(storeFileName));
    
    return ResponseEntity.ok()
        .header(HttpHeaders.CONTENT_DISPOSITION, contentDisposition)
        .body(resource);
}

Content Disposition 헤더를 넣어주면, 브라우저에서 리소스임을 인식해서 다운로드 해준다. (아니면 URL 링크로 인식함)

참고로 멀티파트 데이터는 아래와 같은 HTTP 헤더를 가진다.