Real Storage

@realbase/real-storage 패키지는 파일 저장소 서비스인 RealStorage와 상호작용하기 위한 Next.js 전용 도구를 제공합니다. 이 패키지는 파일 업로드, 다운로드, 삭제 및 기타 파일 관리 작업을 간편하게 처리할 수 있도록 설계되었습니다.

패키지 구조

이 패키지는 monorepo 환경에서 개발되고 npm으로 배포됩니다:

• package.json: 개발용 (monorepo 패턴, catalog: 및 workspace:* 사용)
• package.deploy.json: 배포용 (실제 버전 번호 사용)

배포 시 package.deploy.json이 최종 package.json으로 사용되어 npm에 게시됩니다.

주요 기능

• 파일 업로드 (진행률 추적 지원)
• 파일 다운로드
• 파일 삭제
• 파일 상태 확인

설치

npm install @realbase/real-storage

환경 변수

다음 환경 변수를 설정해야 합니다:

REALSTORAGE_ACCESS_KEY와 REALSTORAGE_PATH는 realstorage.wooritech.com 에 가입후 발급받을 수 있습니다.

REALSTORAGE_URL='https://realstorage.wooritech.com/api/v1/files' REALSTORAGE_ACCESS_KEY='' REALSTORAGE_PATH='your-file-path'

사용법

React Hook 사용 (권장)

import { useRealStorage } from "@realbase/real-storage";

function FileUploadComponent() {
  const { upload, uploading, uploadProgress } = useRealStorage();

  const handleFileUpload = async (files: File[]) => {
    const fileInfos = files.map((file, index) => ({
      requestId: `upload-${Date.now()}-${index}`,
      file
    }));

    try {
      const result = await upload(fileInfos, (progress) => {
        console.log(`전체 진행률: ${progress.overallPercentage}%`);
        console.log(`현재 파일: ${progress.currentFileProgress.fileName}`);
      });
      console.log("업로드 완료:", result);
    } catch (error) {
      console.error("업로드 실패:", error);
    }
  };

  return (
    <div>
      <input
        type="file"
        multiple
        onChange={(e) => handleFileUpload(Array.from(e.target.files || []))}
      />
      {uploading && (
        <div>
          업로드 중... 
          {uploadProgress && (
            <span>{uploadProgress.overallPercentage}%</span>
          )}
        </div>
      )}
    </div>
  );
}

직접 함수 호출

import { uploadFiles } from "@realbase/real-storage";

// 기본 사용법
const result = await uploadFiles([
  { requestId: "file1", file: file1 },
  { requestId: "file2", file: file2 }
]);

// 진행률 콜백과 함께 사용
const result = await uploadFiles([
  { requestId: "file1", file: file1 },
  { requestId: "file2", file: file2 }
], (progress) => {
  console.log('전체 진행률:', progress.overallPercentage + '%');
  console.log('현재 파일:', progress.currentFileProgress.fileName);
  console.log('현재 파일 진행률:', progress.currentFileProgress.percentage + '%');
});

파일 다운로드

import { useRealStorage } from "@realbase/real-storage";

const { download, downloading } = useRealStorage();

const handleDownload = async () => {
  const result = await download({
    fileKeys: ["fileKey1", "fileKey2"]
  });
  console.log("다운로드 URL:", result?.preSignedUrlInfos);
};

파일 삭제

import { useRealStorage } from "@realbase/real-storage";

const { remove, removing } = useRealStorage();

const handleRemove = async () => {
  const result = await remove({
    fileKeys: ["fileKey1", "fileKey2"]
  });
  console.log("삭제 결과:", result);
};

진행률 추적 기능

진행률 데이터 구조

// 개별 파일 진행률
interface IFileUploadProgress {
  requestId: string;
  fileName: string;
  loaded: number;      // 업로드된 바이트
  total: number;       // 전체 파일 크기
  percentage: number;  // 파일 진행률 (0-100)
}

// 전체 업로드 진행률
interface IOverallUploadProgress {
  currentFileIndex: number;        // 현재 파일 인덱스
  totalFiles: number;             // 전체 파일 수
  currentFileProgress: IFileUploadProgress;  // 현재 파일 진행률
  overallLoaded: number;          // 전체 업로드된 바이트
  overallTotal: number;           // 전체 파일 크기
  overallPercentage: number;      // 전체 진행률 (0-100)
}

진행률 콜백 사용 예시

const handleUploadWithProgress = async (files: File[]) => {
  const fileInfos = files.map((file, index) => ({
    requestId: `upload-${index}`,
    file
  }));

  await uploadFiles(fileInfos, (progress) => {
    // 전체 진행률 표시
    console.log(`전체: ${progress.overallPercentage}% (${progress.currentFileIndex + 1}/${progress.totalFiles})`);
    
    // 현재 파일 진행률
    const current = progress.currentFileProgress;
    console.log(`현재 파일 "${current.fileName}": ${current.percentage}%`);
    
    // UI 업데이트
    updateProgressUI({
      overall: progress.overallPercentage,
      currentFile: current.fileName,
      currentFileProgress: current.percentage
    });
  });
};