📌 Spring 파일 다운로드 + 파일 리스트 출력 총정리

📅 날짜

2025-04-28

---

📝 학습 내용

1️⃣ 파일 다운로드 컨트롤러 구현

@GetMapping(value="/download", produces = MediaType.APPLICATION_OCTET_STREAM_VALUE)
@ResponseBody
public ResponseEntity<Resource> download(@RequestParam("path") String path) throws UnsupportedEncodingException {
    log.info("GET /file/download..." + path);

    // 파일 리소스 생성
    Resource resource = new FileSystemResource(path);

    // 파일 존재 여부 체크
    if (!resource.exists()) {
        return new ResponseEntity<>(HttpStatus.NOT_FOUND);
    }

    // 다운로드 파일명 추출
    String filename = resource.getFilename();

    // HTTP 헤더 설정
    HttpHeaders headers = new HttpHeaders();
    headers.add(
        "Content-Disposition",
        "attachment; filename=" + new String(filename.getBytes("UTF-8"), "ISO-8859-1")
    );

    // 파일 리소스 + 헤더 + 성공 상태코드 함께 반환
    return new ResponseEntity<>(resource, headers, HttpStatus.OK);
}

---

2️⃣ 파일 다운로드 처리 핵심 포인트

항목	설명
@GetMapping("/download")	파일 다운로드 요청을 처리하는 엔드포인트
produces = MediaType.APPLICATION_OCTET_STREAM_VALUE	브라우저가 파일로 인식해서 다운로드하게 함
Resource resource = new FileSystemResource(path)	요청받은 경로의 파일을 Resource 객체로 생성
resource.exists()	파일이 존재하지 않으면 404 Not Found 반환
Content-Disposition 헤더 설정	파일 다운로드 방식으로 변환 (attachment)
파일명 인코딩	UTF-8 ➔ ISO-8859-1 변환 (한글, 특수문자 깨짐 방지)
ResponseEntity<Resource> 반환	본문 + 헤더 + HTTP 상태코드를 함께 전달

---

3️⃣ 파일 리스트 출력 JSP 흐름

<h1>/file/list</h1>
<div>${uploadPath}</div>

<!-- 업로드 폴더 구조 순회 -->
<c:forEach items='${uploadPath.listFiles()}' var='subdir'>
    <hr>
    FOLDER : ${subdir.getPath()}
    <c:forEach items='${subdir.listFiles()}' var='file'>
        <br />
        - FILE :
        <a href="javascript:void(0)" class="item"
           data-dir="${subdir.getPath()}" data-filename="${file.getName()}">
           ${file.getPath()}
        </a>
    </c:forEach>
    <hr>
</c:forEach>

<script>
const projectPath = '${pageContext.request.contextPath}';
const item_els = document.querySelectorAll('.item');
item_els.forEach((item)=>{
    item.addEventListener('click', function(){
        const filepath = encodeURIComponent(item.getAttribute('data-dir') + "\\" + item.getAttribute('data-filename'));
        location.href = projectPath + "/file/download?path=" + filepath;
    })
})
</script>

---

4️⃣ 파일 리스트 출력 흐름 핵심 포인트

항목	설명
uploadPath.listFiles()	최상위 업로드 디렉토리의 서브 폴더들을 순회
subdir.listFiles()	각 서브 폴더 내부 파일 리스트 출력
<a> 링크 클릭 시	파일 다운로드 요청 발생
encodeURIComponent	파일 경로를 URL-safe 형식으로 인코딩하여 서버로 전송
실무 주의사항	서버의 파일 시스템 경로를 직접 사용자에게 제공하면 안 됨

---

🔥 최종 정리

• 다운로드 기능은 Resource 객체를 통해 파일을 읽고, 적절한 헤더를 추가하여 클라이언트로 반환하는 방식으로 구현한다.
• 파일명에 한글이나 특수문자가 포함되어 있을 경우 반드시 UTF-8 ➔ ISO-8859-1 인코딩을 적용하여 깨짐을 방지해야 한다.
• 파일이 존재하지 않을 경우 404 에러를 반환하여 사용자 경험을 개선한다.
• 파일 리스트 출력은 JSP에서 업로드된 폴더와 파일들을 순회하여 출력하고, 파일별 다운로드 링크를 제공한다.
• 다운로드 링크 요청 시 파일 경로를 안전하게 인코딩하여 서버에 전달한다.
• 보안상, 파일 시스템 경로를 직접 제공하는 것은 위험하므로 실무에서는 데이터베이스 연동 방식으로 보완할 필요가 있다.

---

🔗 참고 자료

• Spring 공식 문서 - 파일 다운로드
• Apache Commons IO

---