Files SDK

Files SDK: 객체 및 블롭 스토리지를 위한 강력한 통합 스토리지 SDK

현대적인 웹 애플리케이션 개발에서 데이터 저장소의 선택은 매우 중요합니다. 하지만 AWS S3, Cloudflare R2, Vercel Blob 등 각 서비스 공급자마다 서로 다른 SDK와 API 구조를 가지고 있어, 스토리지를 교체하거나 여러 플랫폼을 동시에 사용하는 작업은 개발자에게 큰 부담이 됩니다. Files SDK는 이러한 문제를 해결하기 위해 탄생한 객체 및 블롭 백엔드용 통합 스토리지 SDK입니다.

Files SDK는 여러 공급자의 복잡한 기능을 단일한 클래스 뒤로 숨기고, 가장 핵심적인 기능인 업로드, 다운로드, 목록 조회, 삭제 기능을 표준화하여 제공합니다. 이 글에서는 Files SDK의 특징부터 사용법, 활용 사례까지 상세히 살펴보겠습니다.

---

What's Files SDK (Files SDK란 무엇인가요?)

Files SDK는 다양한 객체 스토리지 및 블롭 스토리지를 위한 단일화된 인터페이스를 제공하는 통합 SDK입니다. 이 라이브러리의 핵심 철학은 "하나의 작고 정직한 API(One small, honest API)"를 제공하는 것입니다. 공급자마다 미묘하게 다른 SDK 사용법을 익힐 필요 없이, Files SDK 하나만으로 여러 스토리지를 제어할 수 있습니다.

또한, Files SDK는 웹 표준 I/O를 기반으로 설계되어 Node.js, Bun, Cloudflare Workers, Vercel Edge Function 등 fetch가 실행되는 모든 환경에서 완벽하게 작동합니다. 만약 특정 공급자만이 가진 고유한 기능이 필요하다면, '이스케이프 해치(Escape hatch)' 기능을 통해 언제든지 네이티브 클라이언트에 접근할 수 있는 유연성도 갖추고 있습니다.

---

Files SDK의 주요 기능 (Features)

Files SDK는 개발자 경험(DX)을 극대화하기 위해 다음과 같은 강력한 기능들을 제공합니다.

1. 공급자 간 단일 API (Unified API)

여러 스토리지 공급자를 사용하더라도 코드를 다시 작성할 필요가 없습니다. Files SDK는 업로드(upload), 다운로드(download), 목록 조회(list), 삭제(delete) 등의 공통 작업을 일관된 메서드로 제공하므로, 설정의 어댑터만 교체하면 즉시 다른 스토리지로 전환이 가능합니다.

2. 웹 표준 I/O 지원

Files SDK는 현대적인 웹 표준을 준수합니다. 다음과 같은 다양한 데이터 형식을 직접 입력받을 수 있습니다.

• File 및 Blob
• ReadableStream
• ArrayBuffer
• String

3. 이스케이프 해치 (Escape Hatch)

표준 API만으로는 부족한 경우가 있습니다. Files SDK는 files.raw 속성을 통해 해당 어댑터의 네이티브 클라이언트에 직접 접근할 수 있게 해줍니다. 이를 통해 버전 관리, 생명주기 설정, ACL(액세스 제어 목록), 멀티파트 업로드 등 공급자 전용 기능을 제약 없이 사용할 수 있습니다.

4. 예측 가능한 에러 처리

공급자마다 에러 메시지와 코드가 달라 디버깅이 어려웠던 경험이 있으실 겁니다. Files SDK는 모든 공급자에 대해 정규화된 코드를 가진 단일 FilesError를 발생시킵니다. 원래의 에러는 cause 속성에 첨부되어 있어 상세한 분석이 가능합니다.

---

Files SDK 설치 방법 (Installation)

Files SDK는 프로젝트 환경에 맞는 패키지 매니저를 통해 간단히 설치할 수 있습니다.

npm install files-sdk
# 또는
pnpm install files-sdk
# 또는
bun add files-sdk
# 또는
yarn add files-sdk

주의사항: 각 공급자의 네이티브 SDK는 선택적 피어 종속성(Optional peer dependency)입니다. Files SDK 전체를 설치할 때 모든 SDK가 포함되지 않으므로, 실제로 사용하는 어댑터에 필요한 패키지만 별도로 설치하여 프로젝트 크기를 최적화할 수 있습니다. 만약 어댑터를 임포트했지만 관련 패키지가 없다면 ERR_MODULE_NOT_FOUND 에러가 발생합니다.

---

How to Use (사용 방법)

Files SDK를 사용하는 방법은 매우 직관적입니다. 먼저 사용할 공급자의 어댑터와 함께 Files 인스턴스를 생성한 후 메서드를 호출하면 됩니다.

1. 인스턴스 생성 및 초기화

다음은 AWS S3 어댑터를 사용하여 Files SDK를 설정하는 예시입니다.

import { Files } from "files-sdk";
import { s3 } from "files-sdk/s3";

const files = new Files({
  adapter: s3({ bucket: "uploads", region: "us-east-1" }),
});

2. 기본 작업 수행

설정된 files 객체를 통해 파일 작업을 수행합니다.

• 파일 업로드: await files.upload("hello.txt", "world");
• 파일 다운로드: const file = await files.download("hello.txt");
• 파일 메타데이터 확인: const meta = await files.head("hello.txt");
• 파일 목록 조회: const { items } = await files.list({ prefix: "hello" });
• 파일 삭제: await files.delete("hello.txt");

---

활용 사례 (Use Case)

1. 멀티 클라우드 및 벤더 락인 방지

특정 스토리지 서비스의 가격이 오르거나 서비스 품질이 저하될 경우, Files SDK를 사용 중이라면 비즈니스 로직을 수정하지 않고도 어댑터 설정만 변경하여 S3에서 Cloudflare R2나 Google Cloud Storage로 손쉽게 이전할 수 있습니다.

2. 다양한 실행 환경 대응

Files SDK는 가벼운 구조와 웹 표준 준수 덕분에 Node.js 서버뿐만 아니라 Edge 컴퓨팅 환경(Vercel, Cloudflare Workers)에서도 문제없이 작동합니다. 서버리스 아키텍처에서 스토리지를 다룰 때 최적의 선택입니다.

3. 로컬 개발 환경 구축

실제 클라우드 스토리지를 사용하기 어려운 개발 초기 단계에서 Filesystem 어댑터를 사용하여 로컬 디렉토리에 파일을 저장하고, 배포 시에만 S3 어댑터로 교체하는 방식으로 효율적인 워크플로우를 구성할 수 있습니다.

---

호환성 매트릭스 (Compatibility Matrix)

Files SDK는 업계에서 사용되는 거의 모든 주요 스토리지 서비스를 지원합니다. 지원되는 주요 어댑터 목록은 다음과 같습니다.

• 클라우드 대기업: AWS S3, Google Cloud Storage (GCS), Azure, IBM COS, Oracle Cloud.
• 최신 블롭 서비스: Cloudflare R2, Vercel Blob, Netlify Blobs, Supabase, UploadThing.
• 특화 스토리지: DigitalOcean, MinIO, Bun S3, Backblaze B2, Bunny Storage, Scaleway, Vultr.
• 기타 서비스: Dropbox, Google Drive, OneDrive, SharePoint, Box, Cloudinary, Firebase Storage, PocketBase.

각 어댑터는 업로드, 다운로드, 삭제, 목록 조회 등 10가지 핵심 메서드를 동일하게 구현합니다. (일부 서비스의 특성에 따라 URL 생성 방식 등에 차이가 있을 수 있습니다.)

---

자주 묻는 질문 (FAQ)

Q: 사용하지 않는 공급자의 SDK까지 모두 설치되나요? A: 아니요. Files SDK는 피어 종속성 구조를 사용하므로, 여러분이 실제로 코드에서 사용하는 어댑터의 SDK만 설치하면 됩니다. 이를 통해 번들 크기를 최소화할 수 있습니다.

Q: 에러가 발생했을 때 원래 공급자의 에러 메시지를 볼 수 있나요? A: 네, 가능합니다. Files SDK는 FilesError라는 표준화된 에러를 던지지만, cause 속성에 원래 공급자 SDK에서 발생한 원본 에러 객체를 포함하고 있습니다.

Q: 한 번 생성한 Files 인스턴스에서 공급자를 동적으로 바꿀 수 있나요? A: Files SDK의 인스턴스는 생성 시점에 어댑터가 고정됩니다. 이는 코드의 예측 가능성을 높이기 위함입니다. 다른 공급자가 필요하다면 새로운 Files 인스턴스를 생성하여 사용하는 것을 권장합니다.

Q: 특정 서비스에서만 지원하는 특수 기능(예: S3 ACL)은 어떻게 사용하나요? A: files.raw 속성을 사용하세요. 해당 어댑터가 사용하는 네이티브 클라이언트에 직접 접근하여 모든 특수 기능을 사용할 수 있습니다.