제 블로그 프로젝트인 **Code Masterpiece**를 개발하면서 가장 공을 들인 부분 중 하나는 의외로 **파일 시스템**이었습니다. 사실, 파일 업로드는 겉보기엔 단순합니다. 라이브러리 하나 가져와서 S3에 `putObject`만 하면 끝나는 일처럼 보이니까요. 하지만 저는 단순한 기능 구현을 넘어, **'운영하면서 짐이 되지 않는 시스템'**을 만들고 싶었습니다. "나중에 고치지 뭐"라고 생각하는 순간, 불필요한 비용과 기술 부채는 제 몫이 되니까요. 가장 신경 쓰였던 건 **데이터의 분리**였습니다. 파일의 실체는 S3(스토리지)에, 정보는 DB에 있습니다. 이 둘은 사는 세상이 다릅니다. 저는 이 둘 사이의 **어긋남(Inconsistency)**을 1%도 허용하고 싶지 않았습니다. # 내가 해결하고 싶었던 '찝찝함'들 (Pain Points) 단순히 돌아가는 코드가 아니라, **깔끔한 코드**를 위해 저는 다음 네 가지 문제를 반드시 해결하고 넘어가기로 했습니다. #### 1. 내 돈을 갉아먹는 '고아 파일(Orphan File)' 게시글을 쓰다 이미지를 올리고, 마음이 바뀌어 취소 버튼을 누릅니다. 혹은 게시글을 삭제합니다. 이때 DB 데이터는 사라지지만, S3에 올라간 파일은 그대로 남습니다. 물론 용량 몇 KB 안 될 수도 있습니다. 하지만 엔지니어로서 **아무도 참조하지 않는 쓰레기 파일**이 내 스토리지에 계속 쌓이는 걸 보고만 있을 수는 없었습니다. 서비스가 커질수록 이 '죽은 파일'들은 고스란히 비용 청구서로 돌아오게 됩니다. #### 2. "이미지가 깨져 보여요" - 정합성의 딜레마 DB에는 파일 정보가 있는데 실제 S3 업로드가 실패했거나, 반대로 파일은 올라갔는데 DB 저장이 실패하는 경우. 이 두 작업은 물리적으로 분리되어 있어 **하나의 트랜잭션**으로 묶기가 어렵습니다. 제 블로그에서 엑스박스(이미지 깨짐) 아이콘을 보는 건 끔찍한 경험일 겁니다. 저는 시스템 레벨에서 이 불일치를 막고 싶었습니다. #### 3. 느린 건 못 참아 (동기 처리의 한계) 고화질 이미지를 업로드한다고 가정해 봅시다. 원본 저장, 썸네일 생성, WebP 변환까지 다 끝날 때까지 사용자가 로딩 바만 쳐다보고 있어야 할까요? 저는 업로드 버튼을 누르면 **즉시** 반응하길 원했습니다. 무거운 작업 때문에 사용자 경험을 해치고 싶지 않았습니다. #### 4. AWS에 락인(Lock-in) 되기 싫은 마음 코드 여기저기에 `s3Client.putObject()`가 박혀있는 구조는 싫었습니다. 로컬 환경에서 개발하거나, 나중에 다른 클라우드로 이사를 갈 수도 있으니까요. 비즈니스 로직이 특정 인프라 SDK에 종속되는 것을 막고, **테스트하기 좋은 구조**를 만들고 싶었습니다. ---
# 설계: 모든 것은 아키텍처 설계부터 앞서 나열한 '찝찝함'들을 해결하기 위해 제가 선택한 방법은 복잡한 기술이나 새로운 라이브러리가 아니었습니다. 오히려 가장 기본적이고 원칙적인 **객체지향 프로그래밍(OOP)**의 지혜를 빌렸습니다. 바로 **단일 책임 원칙(SRP, Single Responsibility Principle)**입니다. ## 1) 파일 저장의 두 개념: Brain vs Hands 우리가 흔히 말하는 "파일을 저장한다"라는 행위는 사실 컴퓨터 관점에서 보면 성격이 완전히 다른 두 가지 작업이 합쳐진 것입니다. 1. **정보의 기록 (Metadata):** "이 파일은 누구의 것이며, 이름은 무엇이고, 어디에 속해 있는가?"를 DB에 적는 행위. 2. **데이터의 보관 (Physical I/O):** 실제 바이너리 데이터(0과 1)를 하드디스크나 S3 같은 물리적 공간에 덩어리째 옮기는 행위. 대부분의 스파게티 코드는 이 두 가지를 하나의 서비스(`FileService`)나 컨트롤러에서 동시에 처리하려고 할 때 발생합니다. 저는 이 둘을 **칼로 자르듯 분리**하는 것부터 시작했습니다. - **`FileService` (Brain):** 오직 파일의 메타데이터(DB)와 생명주기만을 관리합니다. 실제 파일이 S3에 있는지 로컬에 있는지는 관심이 없습니다. - **`IoManager` (Hands):** 오직 물리적인 I/O(put/get)만을 수행합니다. 비즈니스 로직은 전혀 모르는 순수한 인프라 계층입니다. ### 복잡함은 감추고, 책임은 독점한다: 파사드(Facade) 여기서 저는 시스템의 안정성을 위해 구조적으로는 **파사드(Facade) 패턴**을 적용하되, 타협할 수 없는 **절대 원칙**을 하나 세웠습니다. > **"IoManager(손)는 오직 FileService(뇌)의 지시로만 움직여야 한다."** `FileService`는 뒤에 숨겨진 복잡한 하위 시스템(DB 트랜잭션, S3 업로드, 경로 생성 등)을 완벽하게 가리고, 외부에는 `store()`라는 단순한 인터페이스만 노출합니다. 다른 서비스가 `IoManager`를 직접 주입받아 호출하는 것은 금지됩니다. 왜 이렇게까지 엄격하게 **통제**할까요? 1. **'유령 파일'의 원천 차단:** 만약 개발자가 `FileService`를 거치지 않고 직접 파일을 업로드한다면, S3에는 존재하지만 DB에는 없는 '관리되지 않는 파일'이 생겨납니다. 이들은 나중에 추적할 수도, 지울 수도 없는 디지털 쓰레기가 됩니다. 2. **정책(Policy)의 일관성:** 파일을 "어떤 경로에(Path Strategy)", "어떤 이름으로" 저장할지는 인프라가 아닌 **도메인의 규칙**입니다. 모든 요청이 `FileService`라는 단 하나의 관문을 통과하게 함으로써, 시스템 전체의 파일 저장 규칙을 일관되게 유지할 수 있습니다. 결국 `FileService`는 단순한 저장소가 아니라, 시스템의 정합성을 지키는 **문지기(Gateway)**이자 **컨트롤 타워**인 셈입니다.
## 2) 파일의 세부 요소들: 계층적 설계 '파일'이라는 개념을 잡았다면, 이제 그 아래에 있는 구체적인 녀석들을 정의할 차례입니다. 파일 시스템에는 이미지도 있고, 비디오도 있고, 엑셀 파일도 있습니다. 이들은 모두 '파일'이지만, 각자 해야 할 일은 다릅니다. 저는 이 관계를 **포함(Composition)**과 **규격화(Interface)**로 풀었습니다. - **`FileService` (General):** 모든 파일의 공통 부모 역할. 저장하고, ID를 만들고, 메타데이터를 관리합니다. - **`ImageService` / `VideoService` (Special):** 각자의 특화된 도메인입니다. 이들은 `FileService`를 주입받아 기본적인 파일 기능을 수행하고, 자신만의 **특수 기능(Variant Processing)**을 덧붙입니다. 이미지 서비스는 파일 서비스에게 "일단 저장해 줘"라고 부탁하고, 그 뒤에 "이제 썸네일 만들자"라고 자신의 일을 시작하는 식입니다. ### 공통 기능은 '도구'로 사용 (Composition) 먼저, 모든 파일이 공통적으로 가져야 할 기능(저장, 메타데이터 생성, 경로 관리)은 앞서 만든 `FileService`에 위임합니다. - **`FileService` (General):** 파일 시스템의 **'기반(Foundation)'**입니다. - **`ImageService` / `VideoService` (Special):** 각 도메인의 **'전문가(Specialist)'**입니다. 이들은 `FileService`를 주입받아 "일단 저장해 줘"라고 부탁합니다. ### 흐름의 규격화 (Polymorphism) 하지만 단순히 `FileService`를 사용하는 것만으로는 부족합니다. 이미지든 비디오든 **"원본 저장 후 → 변환 작업(Variant Processing)을 비동기로 요청한다"**는 업무 프로세스는 동일하기 때문입니다. 저는 이 프로세스를 하나의 **인터페이스(규격)**로 정의했습니다. ```java // 모든 미디어 서비스가 지켜야 할 약속 public interface MediaUploadUseCase { // 저장 후 변환 작업까지 트리거하는 메서드 FileInfo upload(UploadCmd cmd); } ``` 덕분에 `ImageService`와 `VideoService`는 이 규격을 구현(Implement)하여 각자의 방식대로 **'변환 일감(VariantJob)'**을 생성하기만 하면 됩니다. - **`ImageService`:** "저장 완료. 자, 이제 **썸네일과 WebP**를 만드는 일감을 큐에 넣자." - **`VideoService`:** "저장 완료. 자, 이제 **HLS 인코딩**을 하는 일감을 큐에 넣자." 이 구조 덕분에 우리는 새로운 파일 타입(예: `AudioService`)이 추가되어도, 전체 아키텍처를 뜯어고칠 필요 없이 **새로운 구현체만 하나 끼워 넣으면 되는 확장성**을 얻게 되었습니다.
## 3) 배리언트 프로세싱: 사용자에게는 속도를, 서버에는 안정성을 이미지나 비디오 파일은 원본 그대로 서비스하기 어렵습니다. 목록용 썸네일도 필요하고, 트래픽 절감을 위해 `WebP`나 `HLS`로 포맷을 변환하는 과정도 필수적입니다. 이 파생 파일들을 저는 **'배리언트(Variant)'**라고 부릅니다. 하지만 이 작업은 **무겁습니다.** 고해상도 이미지를 리사이징하거나 동영상을 인코딩하는 작업은 CPU를 맹렬하게 소모합니다. 만약 사용자가 업로드 요청을 보냈는데, 서버가 이 변환 작업을 동기(Sync)로 처리한다면 어떻게 될까요? 사용자는 변환이 끝날 때까지 하염없이 로딩 바만 바라봐야 할 것입니다. ### Fire and Forget (비동기 처리) 저는 사용자의 기다림을 0초로 만들고 싶었습니다. 그래서 **'저장'**과 **'후처리'**를 시간적으로 분리했습니다. 1. **Fast Path:** 사용자가 업로드를 요청하면, `FileService`는 원본만 저장하고 즉시 "OK"를 응답합니다. 2. **Slow Path:** 트랜잭션이 커밋된 직후, `VariantProducer`가 일감(`VariantJob`)을 생성해 비동기 대기열에 던집니다. ```java // VariantJob.java: 변환 작업지시서 @Builder public record VariantJob( String fileId, // "이 파일 가지고 작업해" String preset, // "프로필 이미지용으로 변환해" List targets ) {} ``` 이제 백그라운드에 있던 **워커(Worker)**가 이 일감을 받아 리사이징을 수행합니다. 사용자는 이미 쾌적하게 다음 페이지로 넘어간 상태죠. ### CPU 바운드 작업과 스레드 풀 전략 여기서 한 가지 디테일이 더 있습니다. 이미지 변환은 대표적인 **CPU-Bound** 작업입니다. 무턱대고 스레드를 많이 만든다고 빨라지지 않습니다. 오히려 컨텍스트 스위칭 비용 때문에 성능이 떨어지죠. 그래서 저는 `VariantExecutor`의 스레드 풀을 **CPU 코어 수에 맞춰 제한**했습니다. ```java int cores = Runtime.getRuntime().availableProcessors(); exec.setCorePoolSize(Math.max(2, cores / 2)); // 코어의 절반 정도만 사용 exec.setMaxPoolSize(Math.max(2, cores)); ``` 이 설정을 통해 변환 요청이 폭주하더라도, 서버의 CPU가 마비되지 않고 **일정한 처리량(Throughput)**을 유지하며 안정적으로 동작하게 됩니다.
## 4) FileRefService: 파일의 주인을 찾아서 파일 시스템에서 가장 골치 아픈 문제는 **"이 파일, 지워도 되나?"**를 판단하는 것입니다. 게시글이 삭제되었는데 파일이 남아있으면 스토리지 비용 낭비고, 반대로 아직 쓰는데 지워버리면 대형 사고(엑박)입니다. 이 문제를 해결하기 위해 저는 운영체제나 JVM이 메모리를 관리하는 방식인 **참조 카운팅(Reference Counting)** 기법을 도입했습니다. ### Attach & Detach 모든 파일은 혼자 존재할 수 없습니다. 반드시 어딘가(Owner)에 소속되어야 합니다. `FileRefService`는 이 관계를 DB에 기록하고 숫자를 셉니다. - **Attach (사용 선언):** 게시글에 이미지가 첨부되는 순간, `attach()` 메서드가 호출됩니다. `FileRef` 테이블에 "게시글 A가 파일 B를 사용 중"이라는 기록을 남기고, 해당 파일의 **`refCount`를 1 증가**시킵니다. - **Detach (사용 해제):** 게시글이 삭제되거나 이미지가 교체되면, `detach()`가 호출됩니다. 관련 기록을 지우고, **`refCount`를 1 감소**시킵니다.
## 5) FileCleaner (GC): 삭제에도 '유예 기간'이 필요하다 참조 카운팅(`RefCount`)이 0이 되었다고 해서, 그 즉시 S3에서 파일을 `delete` 해버리면 어떻게 될까요? 물론 스토리지 용량은 바로 확보되겠지만, 이는 매우 위험한 도박입니다. - **동시성 이슈:** 막 업로드된 파일(`PENDING`)이라 아직 참조가 안 걸렸는데, GC가 낚아채서 지워버린다면? - **사용자 실수:** 사용자가 게시글을 지웠다가 "아차!" 하고 1분 만에 복구(Undo)를 눌렀는데, 이미지가 날아가고 없다면? 이런 끔찍한 상황을 막기 위해 저는 **'지워도 되는 상태(DELETABLE)'**라는 완충 지대를 두었습니다. 바로 **Mark & Sweep** 전략입니다. ### 파일의 4가지 생명주기 (Life Cycle) 저는 파일의 상태를 명확히 정의하기 위해 `FileStatus`라는 상태 머신을 설계했습니다. 1. **`PENDING` (등록):** 파일이 막 업로드된 상태입니다. 아직 어떤 게시글에도 연결되지 않았습니다. 2. **`ACTIVE` (활성):** `refCount > 0`인 상태. 누군가 이 파일을 사용하고 있습니다. 3. **`DELETABLE` (삭제 대기):** `refCount`가 0이 되었거나, `PENDING` 상태로 너무 오래 방치된 파일입니다. **"곧 지워질 예정"**이라는 뜻이지만, 물리적 파일은 살아있습니다. 4. **`DELETED` (삭제 완료):** S3와 DB에서 완전히 정리된 상태입니다. ### Mark & Sweep: 2단계 청소 전략 매일 정해진 시간, `FileCleaner`가 작동하면 청소는 두 단계로 나뉘어 진행됩니다. #### 1단계: Mark (삭제 대기표 붙이기) 먼저, `ACTIVE`나 `PENDING` 상태이면서 `refCount`가 0인 파일들을 찾습니다. 이 파일들을 바로 지우지 않고, 상태만 `DELETABLE`로 변경하고 **`deletableAt`** 시간을 기록합니다. > "너는 이제 사용되지 않아. 하지만 혹시 모르니 24시간만 기다려 줄게." 이 유예 기간 동안 변동이 일어날 수도 있습니다. 만약 사용자가 삭제를 취소하거나 해당 파일을 다시 참조하면, 파일은 즉시 **`ACTIVE` 상태**로 변합니다. 물리적 파일이 살아있기에 가능한 일입니다. #### 2단계: Sweep (확실하게 보내주기) 그다음, `DELETABLE` 상태로 변경된 지 **24시간이 지난(Expired)** 파일들을 찾습니다. 이들은 충분한 유예 기간을 거쳤음에도 부활하지 못한, 진짜 **'고아 파일'**들입니다. ```java // FileCleaner.java @Scheduled(cron = "0 0 3 * * *") public void nightlyCleanup() { // 1. Mark: refCount 0인 파일들을 DELETABLE로 마킹 int marked = housekeeping.sweepMarkDeletable(); // 2. Sweep: 마킹된 지 24시간 지난 파일들을 물리적 삭제 int purged = housekeeping.purgeExpiredDeletables(Duration.ofHours(24)); } ``` 이제 비로소 `IoManager.delete()`를 호출하여 S3에서 바이너리를 제거하고, DB 상태를 `DELETED`로 확정 짓습니다. 이 2단계 전략 덕분에, 저는 **스토리지 비용 최적화**와 **데이터 안전성**이라는 두 마리 토끼를 모두 잡을 수 있었습니다. 시스템은 부지런히 정리하지만, 결코 성급하게 삭제하지 않습니다. ## 6) 아키텍처 도식화 아무리 코드를 깔끔하게 짜도, 파일 하나만 봐서는 전체 시스템의 흐름을 알 수 없습니다. 특히 저처럼 **비동기 처리(Async)**나 **스케줄러(GC)**가 개입된 복잡한 시스템이라면 더더욱 그렇습니다. 코드는 "어떻게(How)"는 말해주지만, "어디서 어디로(Flow)" 흐르는지는 말해주지 않으니까요. 그래서 저는 코드를 치기 전에 반드시 그림(UML)을 먼저 그립니다. 이 다이어그램은 두 가지 이유에서 필수적입니다. 1. **나를 위한 나침반:** 작업하다 보면 로직에 매몰되어 길을 잃을 때가 있습니다. "어? 여기서 DB를 먼저 갱신하던가?" 헷갈릴 때, 이 설계도는 제가 원래 의도했던 길을 다시 찾아줍니다. 2. **동료를 위한 설득의 도구:** 협업할 때 백 마디 말보다 그림 한 장이 강력합니다. "왜 굳이 IoManager를 분리했어요?"라는 질문에, 이 그림을 보여주면 설명은 10초 만에 끝납니다. 이 그림은 단순한 이미지가 아니라 우리 팀의 **'공통 언어'**이자 **'약속'**이 됩니다. 이 모든 요구사항에 대응한 제 파일 시스템의 최종 설계도입니다. ![file system archi.png](https://cdn.codemasterpiece.com/codemasterpiece/2025/12/07/FL-01KBW532VD7D79T5DPT891BFR2/variants/file_system_archi.avif) ---
# 구현: 산출물을 구현하다 설계도가 완성되었으니, 이제 코드로 옮길 차례입니다. 하지만 바로 `AmazonS3Client`를 주입받아 코드를 짜기 시작하면, 그건 앞서 세운 설계를 무너뜨리는 일입니다. 우리는 **'구현'이 아니라 '설계'를 코드로 옮겨야 합니다.** 그렇기에 저는 모든 기능을 **인터페이스(Interface)**로 먼저 정의했습니다. 이 인터페이스들은 시스템의 구성 요소들이 서로 지켜야 할 **'약속(Contract)'**입니다. 이 약속만 지킨다면, 여러분은 S3 대신 로컬 파일 시스템을 쓰든, RabbitMQ 대신 Kafka를 쓰든 상관없습니다. ## 1) IoManager 가장 먼저 정의할 것은 '물리적 저장소'와의 대화법입니다. `IoManager`는 비즈니스 로직이 AWS S3 SDK나 구체적인 파일 경로를 몰라도 되게 만드는 **표준 규격**입니다. 이 인터페이스를 구현(Implements)하기만 하면, 로컬 디스크든 S3든, 혹은 Azure Blob이든 상관없이 우리 시스템의 스토리지로 사용할 수 있습니다. ```java public interface IoManager { // [Basic I/O] - 반드시 구현해야 함 (Mandatory) /** * 파일을 저장합니다. (S3 PutObject, FileOutputStream 등) */ FileObjectMetadata put(PutCommand cmd) throws IOException; /** * 파일을 물리적으로 삭제합니다. */ boolean delete(String key) throws IOException; /** * 파일의 바이너리 스트림과 메타데이터를 함께 엽니다. */ FileResource openStream(String key) throws IOException; /** * 파일의 메타 정보를 확인합니다. */ Optional head(String key) throws IOException; // [Advanced] - 지원하지 않으면 구현 안 해도 됨 (Optional) /** * Presigned URL(읽기/쓰기) 발급은 스토리지에 따라 지원하지 않을 수 있습니다. * 기본값으로 '지원하지 않음' 예외를 던지도록 설정하여, * 필요한 구현체(예: S3IoManager)에서만 오버라이딩하도록 합니다. */ default String presignRead(String key, Duration ttl) throws IOException { throw new UnsupportedOperationException("Presigned Read not supported"); } default PresignWriteResult presignWrite( String key, Duration ttl, String contentType, long maxSize ) throws IOException { throw new UnsupportedOperationException("Presigned Write not supported"); } record PresignWriteResult(String url, Map headersOrFormFields) {} } ``` > [!tip] > > **Presigned URL이 뭔가요?** > > **상황:** 사용자가 1GB짜리 고화질 영상을 업로드한다고 가정해 봅시다. > > **[방식 A: 전통적인 업로드]** > > 1. 사용자(Client)가 1GB 파일을 우리 서버(Spring Boot)로 전송합니다. > 2. 서버는 이 파일을 받아서 다시 S3로 전송합니다. > 3. **문제점:** 서버의 메모리와 네트워크 대역폭이 1GB만큼 낭비됩니다. 사용자가 몰리면 서버는 뻗어버립니다. > > **[방식 B: Presigned URL]** 여기서 **Presigned URL(미리 서명된 URL)**이 등장합니다. 이것은 **"제한된 시간 동안만 유효한 임시 출입증"**입니다. > > 1. **발급 요청:** 클라이언트가 서버에게 "나 업로드 좀 할게"라고 요청합니다. > 2. **티켓 발급:** 서버는 AWS에게 "내 권한으로 5분짜리 업로드 티켓(URL) 하나만 끊어줘"라고 하고, 이를 클라이언트에게 줍니다 (`presignWrite`). > 3. **직접 업로드:** 클라이언트는 이 URL을 이용해 **서버를 거치지 않고 S3로 직접** 파일을 쏘아 올립니다. 결과적으로 우리 서버는 트래픽 부담에서 완전히 해방됩니다. `IoManager`에 이 기능을 추상화해 둠으로써, 우리는 언제든 **서버 업로드 방식**과 **직접 업로드 방식**을 선택해서 쓸 수 있게 되었습니다. --- ### Tip: 안전한 입출력을 위한 캡슐화 (`PutCommand`, `FileResource`) `IoManager`의 메서드 시그니처를 보면 `MultipartFile`이나 `InputStream`을 날것 그대로 쓰지 않고, 전용 객체로 감싸서 사용합니다. 왜 굳이 한 번 더 감쌌을까요? **1. 들어갈 때: `PutCommand` (리소스 누수 방지)** 파일 업로드는 스트림을 다루는 위험한 작업입니다. 실수로 `close()`를 안 하면 메모리 누수가 발생하죠. `PutCommand`는 **`AutoCloseable`을 구현**하여, `try-with-resources` 구문으로 안전하게 스트림을 닫아줍니다. 또한 웹 계층의 `MultipartFile` 의존성을 인프라 계층에서 격리하는 역할도 합니다. ```java try (var command = PutCommand.from(path, multipartFile)) { ioManager.put(command); } // 여기서 command.close()가 자동 호출되어 스트림이 안전하게 닫힘 ``` **2. 나올 때: `FileResource` (메타데이터 동봉)** 파일을 읽을 때 `InputStream`만 덜렁 리턴하면, 받는 쪽에서는 파일 크기(`Content-Length`)나 타입(`Content-Type`)을 알 길이 없습니다. 그래서 **스트림과 메타데이터를 한 그릇(`FileResource`)**에 담아서 리턴합니다. 덕분에 `head()`와 `get()`을 두 번 호출할 필요 없이, 한 번의 S3 요청으로 데이터와 정보를 모두 가져오는 효율적인 구조가 됩니다. ```java // FileResource.java public record FileResource( InputStream content, // 실제 데이터 스트림 FileObjectMetadata meta // 타입, 길이, 캐싱용 ETag 등 ) implements AutoCloseable { ... } ```
## 2) FileService 다음은 파일의 수명 주기를 관리하는 `FileService`입니다. 이 인터페이스는 **"파일을 시스템에 등록한다"**는 행위의 정의입니다. ```java public interface FileService { /** * [Transaction Essential] * 1. IoManager를 통해 물리 파일 저장 * 2. DB에 메타데이터(StoredFile) 저장 * 3. ID 발급 및 결과 반환 */ FileInfo store(StoreCmd storeCmd); /** * 파일 ID로 메타 정보를 조회합니다. */ Optional getFile(String fileId); /** * 실제 스토리지와 DB 상태를 비교 검증할 때 사용합니다. */ Optional getFileHeadMeta(String fileId); } ``` 이곳의 핵심은 `store()` 메서드입니다. 이 메서드는 **트랜잭션 관리**와 **경로 생성 전략(Path Strategy)**을 캡슐화합니다. 어떤 파일이 들어오든 `FileService`를 통과하면 `FL_`로 시작하는 고유 ID를 가진 관리 대상이 됩니다. ### DTO로 보는 설계 의도 단순히 `MultipartFile`을 받는 게 아니라, 전용 커맨드 객체(`StoreCmd`)와 결과 객체(`FileInfo`)를 사용하는 점을 주목해 주세요. - **Input (`StoreCmd`):** 웹 계층의 요청(`MultipartFile`)이든, 내부 로직의 요청(`byte[]`)이든 상관없이 **'저장할 내용'**을 추상화했습니다. 특히 `Supplier`을 사용하여 스트림을 필요한 시점에 열 수 있도록 지연 로딩을 지원합니다. - **Output (`FileInfo`):** DB 엔티티인 `StoredFile`을 그대로 노출하지 않고, 필요한 정보만 담은 DTO를 반환하여 도메인 모델을 보호합니다. 이 `store()` 메서드를 통과하는 순간, 모든 파일은 `FL_`로 시작하는 고유 ID를 부여받고, 날짜별 폴더 트리에 체계적으로 배치됩니다. > [!warning] > > **절대 원칙: 뒷문은 없다 (No Backdoor)** > > `FileService`와 `IoManager`를 아무리 잘 만들어도, 누군가 **몰래 스토리지에 들어가서 파일을 지우거나 올리면** 모든 정합성은 깨집니다. DB에는 "파일이 있다"고 되어 있는데 실제 디스크에는 없는 **유령 데이터**는 대부분 이런 '뒷문 접근'에서 발생합니다. > > 따라서 **물리적 저장소에 대한 접근 권한 통제**는 아키텍처의 필수 요소입니다. > > 1. **애플리케이션 레벨:** 개발자는 오직 `FileService`를 통해서만 파일에 접근해야 합니다. `IoManager`를 직접 호출하는 코드는 PR 단계에서 반려되어야 합니다. > 2. **인프라 레벨 (가장 중요):** 실제 저장소는 시스템 계정 외에는 **아무도 건드릴 수 없도록** 막아야 합니다. > - **Linux/Local:** 파일이 저장되는 디렉토리 권한(`chmod`, `chown`)을 강력하게 제한하여, 웹 서버 계정 외에는 root조차 함부로 쓰지 못하게 하십시오. > - **Cloud (AWS S3):** 버킷 정책(Bucket Policy)과 IAM을 통해 **Public Access를 차단**하고, 오직 애플리케이션의 IAM Role만이 `Put/Delete`를 할 수 있도록 권한을 최소화하십시오. 콘솔에서 수동으로 업로드하는 것조차 막는 것이 이상적입니다. > > **"물리적 통제가 없는 정합성은 모래 위에 지은 성과 같다"**는 것을 명심해야 합니다.
## 3) MediaUploadUseCase 이제 '이미지'나 '비디오' 같은 구체적인 서비스들이 구현해야 할 규격입니다. 이 인터페이스는 컨트롤러와 도메인 서비스 사이의 **'추상화된 경계'**입니다. ```java public interface MediaUploadUseCase { /** * 파일을 업로드하고, 각 도메인의 정책에 따라 후처리를 수행합니다. * @param cmd 업로드할 파일 정보 * @return 저장된 원본 파일 정보 (FileInfo) */ FileInfo upload(UploadCmd cmd); } ``` 파일에는 다양한 개념들이 포함되어 있습니다. 이미지도 파일이고 비디오도 파일이지요. 하지만 **파일은 이미지가 아닙니다.** 역으로 이미지는 파일의 한 종류일 뿐입니다. 따라서 이미지나 비디오 같은 특수 파일들은 각자에게 특화된 기능(썸네일, 인코딩)이 필요합니다. `MediaUploadUseCase` 구현체들은 `FileService`를 **도구(Composition)**로 사용하여 기본 저장을 수행하고, 그 위에 자신만의 특수 기능을 덧붙입니다. ```java // 예시: 이미지 서비스 구현체 @Service @RequiredArgsConstructor public class ImageUploadService implements MediaUploadUseCase { // fileService를 반드시 이용해야 함 private final FileService fileService; private final VariantProducer variantProducer; @Override public FileInfo upload(UploadCmd cmd) { // 1. 저장 (공통) FileInfo info = fileService.store(cmd); // 2. 후처리 (이미지만의 특화 로직) variantProducer.publish(VariantJob.builder() .fileId(info.fileId()) .target(VariantTarget.THUMBNAIL) .build()); return info; } } ``` 컨트롤러 입장에서는 상대가 이미지 서비스든 문서 서비스든 신경 쓸 필요가 없습니다. 그저 `useCase.upload()`만 호출하면, 나머지는 각 서비스가 알아서 처리하니까요. 이것이 바로 **캡슐화**의 힘입니다. > [!important] > > **원칙: 저장은 전문가(FileService)에게 맡긴다** > > 여기서 `ImageUploadService`가 편의를 위해 `IoManager`를 직접 주입받아 사용하면 **절대 안 됩니다.** > > 파일의 저장 경로를 결정하고(`YYYY/MM/DD`), 고유 ID를 발급하고(`FL_...`), DB에 메타데이터를 남기는 정합성 로직은 오직 **`FileService`만의 고유 권한**이어야 합니다. > > 만약 `ImageService`가 이를 우회해서 직접 파일을 저장하게 되면: > > 1. **중복 코드 발생:** ID 생성, 경로 설정 로직이 서비스마다 복사됩니다. > 2. **정합성 파괴:** `ImageService`에서 저장 로직을 실수로 다르게 구현하면, 시스템 전체의 파일 규칙이 무너집니다. > > `ImageService`는 "이미지 처리"의 전문가일 뿐, "파일 저장"의 전문가는 아닙니다. 자신의 전문 분야가 아닌 일은 과감하게 `FileService`에게 **위임(Delegation)**해야 시스템이 건강하게 유지됩니다. ### 심화: 템플릿 메서드로 '저장 흐름' 강제하기 인터페이스(`MediaUploadUseCase`)만으로는 개발자가 구현체에 `FileService`를 넣을지, 실수로 `IoManager`를 넣을지 통제할 수 없습니다. 이럴 때는 인터페이스 대신 **추상 클래스(Abstract Class)**를 사용하면 좋습니다. ```java // 모든 미디어 서비스의 부모 (추상 클래스) @Getter @RequiredArgsConstructor public abstract class BaseMediaUploadService implements MediaUploadUseCase { // 자식들이 사용할 도구 (protected로 상속) // 생성자가 자동 생성되므로, 자식은 객체 생성 시 이 필드를 필수로 주입해야 함 protected final FileService fileService; } ``` ```java @Service public class ImageUploadService extends BaseMediaUploadService { private final VariantProducer variantProducer; public ImageUploadService(FileService fileService, VariantProducer variantProducer) { super(fileService); this.variantProducer = variantProducer; } @Override public FileInfo upload(UploadCmd cmd) { FileInfo info = fileService.store(cmd); // 이후 자유롭게 로직 구현... variantProducer.publish(VariantJob.builder() .fileId(info.fileId()) .target(VariantTarget.THUMBNAIL) .build()); return info; } } ``` 이 구조 덕분에, 협업하는 동료가 새로운 미디어 서비스를 구현하더라도 **`FileService`의 사용이 강제됩니다.** 생성자에서부터 의존성을 요구하기 때문에, 개발자는 고민 없이(혹은 우회할 방법 없이) 자연스럽게 우리가 정해둔 표준 저장 방식을 따르게 됩니다.
## 4) VariantProducer & Job 다음은 '저장(Sync)'과 '변환(Async)' 사이를 이어주는 메시지 규격입니다. 사용자에게 0.1초라도 더 빠른 응답을 주기 위해, 무거운 변환 작업은 **비동기(Fire and Forget)**로 처리해야 합니다. ### 작업 지시서: `VariantJob` 비동기 워커에게 "이 작업을 해줘"라고 던질 메시지는 **불변(Immutable)**이어야 안전합니다. Java 16의 `record`를 사용하면 아주 깔끔하게 정의할 수 있습니다. ```java /** * 변환 작업 지시서 (Record를 사용하여 불변성 보장) */ @Builder public record VariantJob( String fileId, // 대상 파일 ID String preset, // 변환 정책 (예: "PROFILE", "POST_CONTENT") List targets // 구체적인 변환 타겟 (예: "THUMBNAIL", "WEBP") ) {} ``` ### 일감 발행: `VariantProducer` 생산자(Service)는 소비자가 누구인지, 어떻게 처리하는지 알 필요가 없습니다. 그저 "이 일감 좀 처리해 줘"하고 큐에 넣기만 하면 됩니다. ```java @Component @RequiredArgsConstructor public class VariantProducer { private final TaskExecutor variantExecutor; private final VariantWorker worker; public void publish(VariantJob job) { // 비동기 스레드 풀에 작업을 제출합니다. (Fire and Forget) variantExecutor.execute(() -> { try { worker.handle(job); } catch (Exception e) { // 실패 시 재시도 로직이나 DLQ 처리가 필요할 수 있습니다. log.warn("Variant processing failed. fileId={}", job.fileId(), e); } }); } } ``` > [!tip] > > **엔지니어링 디테일: CPU 바운드 작업과 스레드 풀** > > 이미지 리사이징이나 포맷 변환은 대표적인 **CPU-Bound(연산 중심)** 작업입니다. DB 조회 같은 I/O-Bound 작업과 달리, 스레드를 무한정 늘린다고 빨라지지 않습니다. 오히려 컨텍스트 스위칭 비용 때문에 성능이 떨어집니다. > > 그래서 저는 `VariantExecutor`의 설정을 **CPU 코어 수에 맞춰 제한**했습니다. > > ```java > // VariantExecutorConfig.java > @Bean(name = "variantExecutor") > public ThreadPoolTaskExecutor variantExecutor() { > int cores = Runtime.getRuntime().availableProcessors(); > ThreadPoolTaskExecutor exec = new ThreadPoolTaskExecutor(); > > // 코어 수의 절반~동일 수준으로 제한하여 CPU 점유율 방어 > exec.setCorePoolSize(Math.max(2, cores / 2)); > exec.setMaxPoolSize(Math.max(2, cores)); > > // 큐가 꽉 차면 호출한 스레드가 직접 처리 (Backpressure) > exec.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); > return exec; > } > ``` > > 이렇게 하면 사용자가 갑자기 몰려도 서버의 CPU가 100%를 치며 멈추는(Hang) 현상을 막고, **일정한 처리량(Throughput)**을 유지하며 안정적으로 변환 작업을 수행할 수 있습니다.
## 5) FileRefService 파일 시스템에서 가장 골치 아픈 문제는 **"이 파일, 지워도 되나?"**를 판단하는 것입니다. 게시글이 삭제되었는데 파일이 남아있으면 스토리지 비용 낭비고, 반대로 아직 쓰는데 지워버리면 누군가는 책임을 져야겠지요? 이 문제를 해결하기 위해 저는 운영체제나 JVM이 메모리를 관리하는 방식인 **참조 카운팅(Reference Counting)** 기법을 도입했습니다. ### Attach & Detach: 관계의 정의 모든 파일은 혼자 존재할 수 없습니다. 반드시 어딘가(Owner)에 소속되어야 합니다. `FileRefService`는 이 관계를 DB에 기록하고 숫자를 셉니다. - **Attach (사용 선언):** 게시글에 이미지가 첨부되는 순간, `attach()` 메서드가 호출됩니다. `FileRef` 테이블에 "게시글 A가 파일 B를 사용 중"이라는 기록을 남기고, 해당 파일의 **`refCount`를 1 증가**시킵니다. - **Detach (사용 해제):** 게시글이 삭제되거나 이미지가 교체되면, `detach()`가 호출됩니다. 관련 기록을 지우고, **`refCount`를 1 감소**시킵니다. ```java public interface FileRefService { void attach(AttachCmd cmd); void detach(DetachCmd cmd); // ... } ``` 이제 우리는 복잡한 비즈니스 로직을 다 뒤져볼 필요 없이, 오직 **`refCount`가 0인가?** 만 확인하면 이 파일의 생사를 결정할 수 있습니다. ### replaceAll() 상황에 따라서(보통 대부분의 경우에는) 한번에 배치 처리하는 기능이 필요합니다. `attach`와 `detach`를 하나하나 호출하다가 실수가 발생하기 쉽기 때문입니다. 예를 들어 사용자가 게시글 수정 화면에서 **"이미지 A를 지우고, 이미지 B를 추가하고, 순서를 바꾼 뒤 저장"**을 눌렀다고 가정해 봅시다. 이 복잡한 변경 사항을 `detach` 1번, `attach` 1번, `reorder` 1번... 이런 식으로 계산해서 호출하면 코드는 지저분해지고 버그가 터지기 쉽습니다. ```java /** * 주어진 Owner의 파일 참조 상태를 orderedFileIds와 '정확히 동일한 상태'로 * 원자적으로(Atomically) 교체합니다. */ ReplaceAllResult replaceAll(ReplaceAllCmd cmd); ``` 이 메서드의 존재로 프론트엔드와 백엔드 로직이 단순해집니다. 1. **Front-end:** "삭제된 게 뭐지?" 계산할 필요 없이, 최종적으로 화면에 남은 **파일 ID 목록**만 던지면 됩니다. 2. **Back-end:** 기존 DB 상태와 요청 목록을 비교(Diff)해서 **없어진 건 끄고(Detach), 새로운 건 켜고(Attach), 순서를 맞추는 작업**을 내부적으로 완벽하게 처리합니다.
## 6) FileCleaner (GC) 참조 카운팅(`refCount`)이 0이 되었다고 해서, 그 즉시 S3에서 파일을 `delete` 해버리면 어떻게 될까요? 물론 스토리지 용량은 바로 확보되겠지만, 이는 운영상 매우 위험한 선택입니다. - **동시성 이슈:** 파일이 막 업로드되어 `PENDING` 상태일 때, 아직 게시글과 연결되기 전 찰나의 순간에 GC가 돌아서 파일을 지워버릴 수 있습니다. - **사용자 실수 복구:** 사용자가 게시글을 지웠다가 "아차!" 하고 즉시 복구(Undo) 기능을 사용할 수도 있습니다. 이때 물리 파일이 이미 삭제되었다면 복구할 방법이 없습니다. 이런 상황을 막기 위해 저는 **'지워도 되는 상태(DELETABLE)'**라는 완충 지대를 두었습니다. 컴퓨터 공학에서 가비지 컬렉션이 사용하는 **Mark & Sweep** 전략을 응용한 것입니다. ### Mark & Sweep: 2단계 청소 전략 저는 파일의 상태를 `ACTIVE`, `PENDING`, `DELETABLE`, `DELETED`로 정의하고, 매일 새벽 `FileCleaner` 스케줄러를 통해 두 단계로 청소를 진행합니다. #### 1단계: Mark (삭제 대기표 붙이기) 먼저, `ACTIVE`나 `PENDING` 상태이면서 `refCount`가 0인 파일들을 찾습니다. 이 파일들을 바로 지우지 않고, 상태만 **`DELETABLE`**로 변경하고 현재 시간을 **`deletableAt`**에 기록합니다. 사용되지 않음을 인정하지만 삭제처리는 유예하는 것입니다. 이 유예 기간(Grace Period) 동안에는 언제든 파일이 부활할 수 있습니다. 만약 사용자가 삭제를 취소하거나 해당 파일을 다시 참조하면, 파일은 즉시 `ACTIVE` 상태로 돌아옵니다. 물리적 파일이 살아있기에 가능한 일입니다. #### 2단계: Sweep (확실하게 삭제) 그다음, `DELETABLE` 상태로 변경된 지 **특정 시간 만큼 지난** 파일들을 찾습니다. 이들은 충분한 유예 기간을 거쳤음에도 부활하지 못한, 진짜 **'고아 파일'**들입니다. ```java // FileCleaner.java @Component @RequiredArgsConstructor public class FileCleaner { private final FileHousekeepingService housekeeping; @Scheduled(cron = "0 0 3 * * *", zone = "Asia/Seoul") public void nightlyCleanup() { // 1. Mark: refCount 0인 파일들을 DELETABLE로 마킹 (삭제 대기) int marked = housekeeping.sweepMarkDeletable(); // 2. Sweep: 마킹된 지 24시간 지난 파일들을 물리적 삭제 (영구 삭제) int purged = housekeeping.purgeExpiredDeletables(Duration.ofHours(24)); log.info("Nightly cleanup done. marked={}, purged={}", marked, purged); } } ``` 여기서 `FileHouseKeepingService`는 이러한 파일 status에 따라 한꺼번에 배치 처리하는 로직이 들어가 있습니다. 해당 부분은 직접 비즈니스 로직을 알맞게 작성하면 됩니다. ---
# 마치며: Simplicity does not mean easy. 단순성은 결코 쉬움(Easy)을 의미하지 않습니다. 단순하고 명료한 시스템을 만드는 것은 오히려 가장 어려운 일 중 하나입니다. 물론 제가 오늘 소개한 이 아키텍처가 유일한 정답은 아닙니다. 서비스의 규모와 목적에 따라 더 가벼운 구현이 필요할 수도, 혹은 더 복잡한 분산 처리가 필요할 수도 있습니다. 상황에 맞는 정확한 코드를 작성하는 것이야말로 엔지니어의 가장 중요한 덕목이니까요. 하지만 한 가지 확실한 것은, 우리가 지향하는 **'유지보수하기 좋은 단순한 코드'**는 결코 키보드에 손을 올리고 막바로 작성한다고 해서 만들어지지 않는다는 점입니다. 오히려 그 반대입니다. **설계 단계에서부터 천천히, 그리고 깊이 있게 고민해야만 합니다.** 어떤 책임을 분리할지, 데이터의 흐름을 어떻게 제어할지 고민하는 그 '느린 생각'의 시간들이 쌓여야만, 비로소 실전에서 **빠르고 정밀하게 동작하는 단순성**을 얻을 수 있습니다. 결국 좋은 아키텍처란, 복잡한 현실의 문제를 단순하게 풀어내기 위해 우리가 쏟아부은 치열한 고민의 기록이 아닐까 합니다.