📌”파일 하나 저장하는 일에도, 확장성과 보안을 담았다 – FileUploadUtil 설계기”

🗓 2025년 4월 28일

✍️ by 박찬희

---

🧭 왜 만들었나? 단순 저장으로는 부족했다

강의 플랫폼에선 파일 업로드가 일상이다.

썸네일, 영상, 자막, PDF 등 각기 다른 리소스들이 사용자 손을 타고 서버에 저장된다.

그런데, 단순히 FileOutputStream으로 저장만 한다면?

• 경로가 꼬이고,
• JSP에서 접근이 복잡해지고,
• 추후 AWS S3 같은 외부 저장소로의 이관이 불가능한 코드가 된다.

그래서 나는 ‘진짜 유틸리티답게 작동하는 파일 저장 클래스’를 만들기로 했다.

경로 관리, 보안, 확장성, JSP 추상화까지 모두 한 번에 잡을 수 있도록.

---

🎯 구현 목표 요약

요구사항	설명
📁 구조화된 저장 경로	thumb/, video/, subtitle/ 등으로 구분 저장
🔑 UUID 파일명	중복 방지 + 사용자 파일명 보안 추상화
🌐 JSP 접근 경로 자동 생성	서버 디렉토리 구조와 무관한 /upload/... 경로 반환
💥 예외 처리	저장 실패시 정확한 예외 throw
🔧 확장성	로컬 외 S3, NAS 등으로 쉽게 전환 가능해야 함

---

🧩 구현 코드 (핵심 요약)

public class FileUploadUtil {

  public static String saveFileToLocal(String subDir, String fileName, byte[] fileBytes, String baseDir) throws IOException {
    File dir = new File(baseDir + "/" + subDir);
    if (!dir.exists()) dir.mkdirs();  // ⛏ 하위 디렉토리까지 자동 생성

    File file = new File(dir, fileName);
    try (FileOutputStream fos = new FileOutputStream(file)) {
      fos.write(fileBytes);  // ✅ 실제 파일 저장
    }

    return "/upload/" + subDir + "/" + fileName;  // 🌐 JSP 접근용 상대 경로 반환
  }
}

💡 구현 철학

• 순수 Java 유틸: 의존성 없는 static 구조로 가볍고 이식성 높음
• 경로 추상화: 실제 저장 경로 ↔ JSP 경로를 명확히 분리
• 예외 처리 위임: IOException을 밖으로 throw → Controller 단에서 사용자 메시지 분리 대응 가능

---

🔐 보안을 고려한 설계 요소

보안 리스크	대응 전략
디렉토리 트래버설 (../)	subDir, fileName에서 .. 등 특수 문자 필터링 (추후 개선 가능)
실행 파일 업로드	.exe, .jsp 등 허용되지 않은 확장자 → Controller에서 reject
저장 경로 노출	/upload/**는 Tomcat static 리소스로만 매핑, 내부 저장 구조는 감춤
하드코딩 위험	baseDir은 application.properties 등으로 외부 설정화 예정

---

🧪 테스트 시나리오 & 검증 결과

시나리오	기대 결과
썸네일 저장	/upload/thumb/lecture-uuid.png 경로 반환
10MB 영상 저장	C:/lecture_uploads/video/uuid.mp4 정상 저장 확인
디스크 full	IOException 발생 → 컨트롤러에서 사용자 에러 처리
한글 파일명	한글강의.mp4 문제 없이 저장 (UTF-8 보장 환경)

---

🧱 실제 사용 예시

💼 Controller 단

String uuid = UUID.randomUUID().toString();
String fileName = "lecture-" + uuid + ".jpg";
String savedUrl = FileUploadUtil.saveFileToLocal("thumb", fileName, imageBytes, BASE_DIR);

🖼 JSP 단

<img src="${savedUrl}" alt="강의 썸네일">

✅ JSP는 더 이상 저장 경로를 몰라도 된다.

단지 /upload/로 시작하는 상대 URL만 알면 끝이다.

---

🧠 기술적 키워드 요약

키워드	의미
FileOutputStream	Java I/O 기반 파일 저장의 기본
try-with-resources	자원 자동 해제 → 메모리 누수 예방
mkdirs()	존재하지 않는 모든 하위 디렉토리까지 생성
JSP 경로 추상화	저장소 경로와 클라이언트 접근 경로 분리
순수 유틸리티화	상태 없는 static 함수 → 테스트와 확장에 최적

---

🌱 향후 확장 계획

• FileUploadStrategy 인터페이스 도입

  → LocalUploadStrategy, S3UploadStrategy, NASUploadStrategy 등 구현체 교체만으로 저장 방식 변경 가능

• MIME 타입 자동 분기

  → 이미지, 영상, 자막에 따라 자동으로 thumb/, video/, subtitle/ 디렉토리 지정

• 업로드 로그 기록

  → 업로드 시간, 유저 ID, IP, 파일명 등을 DB에 저장하여 보안 감사 가능

---

✅ 최종 결과 & 회고

• JSP 기반 웹 시스템에서 안정적인 업로드 경로 관리 체계를 완성
• 코드 구조는 단일 책임 원칙(SRP)을 따르며, 각 레이어에서 역할 분리가 명확
• 컨트롤러에선 저장 경로나 I/O 관련 복잡도를 신경 쓰지 않아도 됨
• 다양한 도메인(강의, 멘토링, 카트 이미지)에서 재사용 중

---

“파일 저장은 단순한 작업처럼 보이지만,

경로 설계, 예외 흐름, 보안, 추상화를 고민하지 않으면 금세 유지보수 지옥이 된다.”

이 유틸 하나로, 파일 저장 로직은 이제 더 이상 나를 괴롭히지 않는다.