Files SDK

Files SDK란?

Files SDK는 오브젝트 및 블롭 스토리지 백엔드와 상호작용하기 위한 단일하고 일관된 API를 제공하는 통합 스토리지 SDK입니다. 목표는 업로드, 다운로드, 목록 조회, 삭제 등 고수준 작업을 동일하게 호출하면서 실제로는 다양한 제공자를 사용할 수 있게 하는 것입니다.

요청은 제공자별 어댑터를 통해 라우팅됩니다. 이를 통해 스토리지 워크플로의 공통 부분은 안정적으로 유지하면서, URL 관련 동작이나 특정 엣지 케이스 같은 제공자 차이는 어댑터 내에서 처리되어 호출 코드를 변경할 필요가 없습니다.

주요 기능

• 단일 Files 클래스: S3, R2, GCS, Azure 등 다양한 제공자에서 업로드, 다운로드, 목록 조회, 삭제, head, exists, copy, URL 헬퍼 등 공통 스토리지 작업을 하나의 API로 수행할 수 있습니다.
• 생성 시 어댑터 지정: new Files({ adapter: ... })로 인스턴스를 생성할 때 어댑터를 고정하여, 호출마다 제공자를 선택하는 패턴을 피할 수 있습니다.
• 웹 표준 입력 지원: 업로드 시 File, Blob, ReadableStream, ArrayBuffer, string을 입력으로 받습니다.
• fetch 기반 실행: Node, Bun, Workers, Vercel 등 fetch가 지원되는 환경에서 일관된 동작을 제공합니다.
• files.raw를 이용한 제공자 접근: 필요 시 files.raw를 통해 해당 제공자의 네이티브 클라이언트에 직접 접근할 수 있습니다.
• 정규화된 에러 처리: 모든 제공자에서 FilesError로 에러를 표준화하여 반환하며, 원래 제공자 에러는 cause로 연결됩니다.

Files SDK 사용 방법

1. SDK 설치 (사용할 어댑터만 peer dependency로 설치):
   • npm install files-sdk
2. Files와 어댑터를 import하고, 버킷/지역을 설정한 어댑터로 Files 인스턴스를 생성합니다 (예: S3).
3. 공유 메서드 호출:
   • files.upload(key, input)
   • files.download(key)
   • files.head(key)
   • files.list({ prefix })
   • files.delete(key)
4. files.raw 사용: 공통 API에 포함되지<|eos|>

대안

• 공급자별 스토리지 SDK(S3/GCS/Azure 네이티브 클라이언트 등): 각 백엔드마다 별도의 코드 경로가 필요하고 공통 작업을 따로 처리해야 합니다.
• 웹 표준 입력을 지원하지 않는 오브젝트 스토리지 추상화 계층: 통합 인터페이스를 제공하지만 동일한 웹 네이티브 입력 유형이나 fetch 기반 런타임 가정을 지원하지 않을 수 있습니다.
• 스토리지 백엔드 옵션이 있는 서버 측 파일 업로드 라이브러리: 업로드 처리에 초점을 맞춘 경우 유용하지만, 동일한 표준화된 작업(head/exists/copy/url 헬퍼)과 네이티브 클라이언트에 대한 탈출구를 제공하지 않을 수 있습니다.
• 오브젝트/블롭 엔드포인트에 대한 직접 HTTP 통합: 최대한의 제어가 필요하다면 공급자 HTTP API를 직접 호출하는 방식으로 추상화를 피할 수 있지만, 목록 조회, 서명, 오류 표준화 및 공급자 차이점을 애플리케이션에서 직접 처리해야 합니다.