@upload - 🌲 Sonamu

@upload 데코레이터는 파일 업로드를 처리하는 API를 생성합니다. Multipart form-data 요청을 자동으로 파싱하고, 파일 객체를 제공합니다. @api 데코레이터 없이도 독립적으로 사용할 수 있으며, 자동으로 POST 메서드와 multipart 클라이언트(axios-multipart, tanstack-mutation-multipart)를 설정합니다.

업로드 모드

Sonamu는 두 가지 파일 업로드 모드를 제공합니다:

모드	옵션	Context 속성	파일 타입	특징
Buffer (기본)	`consume: "buffer"` 또는 생략	`bufferedFiles`	`BufferedFile[]`	메모리에 로드, MD5 계산/이미지 처리 등 유연한 작업 가능
Stream	`consume: "stream"`	`uploadedFiles`	`UploadedFile[]`	즉시 저장소로 스트리밍, 대용량 파일에 적합

Buffer 모드 (기본)

Buffer 모드는 파일을 메모리에 로드한 후 처리합니다. MD5 해시 계산, 이미지 리사이징 등 파일 내용을 직접 다뤄야 할 때 사용합니다.

import { BaseModelClass, upload, Sonamu } from "sonamu";

class FileModelClass extends BaseModelClass {
  @upload()  // 기본값: consume: "buffer"
  async uploadAvatar() {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];

    if (!file) {
      throw new Error("No file uploaded");
    }

    // MD5 해시로 중복 방지
    const md5 = await file.md5();
    const key = `avatars/${md5}.${file.extname}`;
    const url = await file.saveToDisk("fs", key);

    return { url, filename: file.filename, size: file.size };
  }
}

BufferedFile 객체

class BufferedFile {
  // 원본 파일 이름
  get filename(): string;

  // MIME 타입
  get mimetype(): string;

  // 파일 크기 (bytes)
  get size(): number;

  // 확장자 (점 제외, 예: "jpg", "png")
  get extname(): string | false;

  // 파일 Buffer (메모리에 로드된 데이터)
  get buffer(): Buffer;

  // saveToDisk 후 저장된 URL (Unsigned)
  get url(): string;

  // saveToDisk 후 저장된 Signed URL
  get signedUrl(): string;

  // 원본 Fastify MultipartFile 접근
  get raw(): MultipartFile;

  // MD5 해시 계산
  async md5(): Promise<string>;

  // 파일을 디스크에 저장 (URL 반환)
  async saveToDisk(diskName: DriverKey, key: string): Promise<string>;
}

saveToDisk의 파라미터 순서는 (diskName, key) 입니다.

Stream 모드

Stream 모드는 파일을 메모리에 로드하지 않고 즉시 저장소로 스트리밍합니다. 대용량 파일 업로드에 적합합니다.

@upload({
  consume: "stream",
  destination: "s3",  // 저장할 디스크 이름
  keyGenerator: (file) => `uploads/${Date.now()}-${file.filename}`,  // 키 생성 함수
  limits: { files: 5 }
})
async uploadLargeFiles() {
  const { uploadedFiles } = Sonamu.getContext();

  if (!uploadedFiles || uploadedFiles.length === 0) {
    throw new Error("No files uploaded");
  }

  // 파일은 이미 저장소에 업로드된 상태
  return {
    files: uploadedFiles.map((file) => ({
      filename: file.filename,
      url: file.url,
      key: file.key,
      size: file.size,
    })),
  };
}

UploadedFile 객체

Stream 모드에서는 파일이 이미 저장소에 업로드된 상태로 메타데이터만 접근할 수 있습니다.

class UploadedFile {
  // 원본 파일 이름
  get filename(): string;

  // MIME 타입
  get mimetype(): string;

  // 파일 크기 (bytes)
  get size(): number;

  // 확장자 (점 제외, 예: "jpg", "png")
  get extname(): string | false;

  // 저장된 URL (Unsigned)
  get url(): string;

  // 저장된 Signed URL
  get signedUrl(): string;

  // 저장소 내 키
  get key(): string;

  // 저장된 디스크 이름
  get diskName(): DriverKey;

  // 저장소에서 파일 다운로드 (나중에 처리해야 할 때)
  async download(): Promise<Buffer>;
}

옵션

guards

업로드 API에 적용할 가드를 지정합니다. 인증이 필요한 업로드 API에서 사용합니다.

@upload({ guards: ["user"] })
async uploadAvatar() {
  const { user, bufferedFiles } = Sonamu.getContext();
  // user 가드가 적용되어 인증된 사용자만 접근 가능
  // ...
}

description

API 설명을 지정합니다. 자동 생성되는 API 문서에 표시됩니다.

@upload({ description: "사용자 프로필 이미지 업로드" })
async uploadAvatar() {
  // ...
}

limits

파일 업로드 제한을 설정합니다. Fastify multipart의 limits 옵션을 그대로 받습니다.

type UploadDecoratorOptions = {
  // 공통 옵션
  guards?: GuardKey[];    // 적용할 가드 (예: ["user", "admin"])
  description?: string;   // API 설명
  limits?: {
    fileSize?: number;    // 최대 파일 크기 (bytes)
    files?: number;       // 최대 파일 개수
    fields?: number;      // 최대 필드 개수
    fieldSize?: number;   // 최대 필드 크기
    parts?: number;       // 최대 파트 개수
  };
} & (
  // Buffer 모드
  | { consume?: "buffer" }
  // Stream 모드
  | {
      consume: "stream";
      destination: DriverKey;
      keyGenerator?: (file: { filename: string; mimetype: string }) => string;
    }
);

@upload({
  limits: {
    fileSize: 10 * 1024 * 1024, // 10MB
    files: 5,                    // 최대 5개 파일
  }
})
async uploadWithLimits() {
  const { bufferedFiles } = Sonamu.getContext();
  // ...
}

단일 파일 (Buffer)
다중 파일 (Buffer)
Stream 모드

@upload()
async uploadAvatar() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  const md5 = await file.md5();
  return {
    filename: file.filename,
    size: file.size,
    md5
  };
}

@upload({ limits: { files: 10 } })
async uploadDocuments() {
  const { bufferedFiles } = Sonamu.getContext();

  if (!bufferedFiles || bufferedFiles.length === 0) {
    throw new Error("No files");
  }

  const results = [];
  for (const file of bufferedFiles) {
    const md5 = await file.md5();
    const key = `documents/${md5}.${file.extname}`;
    const url = await file.saveToDisk("fs", key);
    results.push({
      filename: file.filename,
      url
    });
  }

  return results;
}

@upload({
  consume: "stream",
  destination: "s3",
  keyGenerator: (file) => `uploads/${Date.now()}-${file.filename}`,
  limits: { files: 5 }
})
async uploadToCloud() {
  const { uploadedFiles } = Sonamu.getContext();

  if (!uploadedFiles || uploadedFiles.length === 0) {
    throw new Error("No files");
  }

  // 파일은 이미 S3에 업로드된 상태
  return uploadedFiles.map((file) => ({
    filename: file.filename,
    url: file.url,
    key: file.key
  }));
}

파일 정보 확인

@upload()
async uploadFile() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  console.log("Filename:", file.filename);
  console.log("MIME type:", file.mimetype);
  console.log("Size:", file.size);
  console.log("Extension:", file.extname);

  return { uploaded: true };
}

파일 처리 (Buffer 모드)

Buffer 접근

@upload()
async processImage() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  // Buffer 직접 접근
  const buffer = file.buffer;

  // 이미지 처리
  const processed = await sharp(buffer)
    .resize(300, 300)
    .toBuffer();

  return { size: processed.length };
}

파일 저장

@upload()
async uploadDocument() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  // 디스크에 저장 (diskName, key 순서)
  const md5 = await file.md5();
  const key = `uploads/${md5}.${file.extname}`;
  const url = await file.saveToDisk("fs", key);

  // 저장된 URL 접근
  console.log("URL:", file.url);
  console.log("Signed URL:", file.signedUrl);

  return { url, filename: file.filename, size: file.size };
}

MD5 해시 계산

@upload()
async uploadWithHash() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  // MD5 해시 계산 (중복 파일 방지에 유용)
  const hash = await file.md5();

  // 해시를 파일명으로 사용
  const key = `uploads/${hash}${file.extname ? `.${file.extname}` : ''}`;
  const url = await file.saveToDisk("fs", key);

  return { url, hash };
}

스토리지 드라이버 사용

Sonamu는 여러 스토리지 드라이버를 제공합니다.

@upload()
async uploadToS3() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  // S3 디스크에 저장 (sonamu.config.ts에서 설정)
  const md5 = await file.md5();
  const key = `avatars/${md5}.${file.extname}`;
  const url = await file.saveToDisk("s3", key);

  return { url };
}

스토리지 드라이버는 sonamu.config.ts에서 설정합니다. 첫 번째 파라미터로 디스크 이름을 전달합니다.

다른 데코레이터와 함께 사용

@transactional과 함께

@upload()
@transactional()
async uploadAndSave() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  const wdb = this.getDB("w");

  // 파일 저장 + DB 업데이트를 트랜잭션으로
  const md5 = await file.md5();
  const key = `documents/${md5}.${file.extname}`;
  const url = await file.saveToDisk("fs", key);

  await wdb.table("documents").insert({
    filename: file.filename,
    url,
    size: file.size,
    created_at: new Date()
  });

  return { url };
}

클라이언트 사용 (Web)

Sonamu는 자동으로 파일 업로드 클라이언트 코드를 생성합니다.

Axios (단일 파일)

import { FileService } from "@/services/FileService";

const formData = new FormData();
formData.append("file", file);

const result = await FileService.uploadAvatar(formData);

Axios (여러 파일)

const formData = new FormData();
files.forEach(file => {
  formData.append("files", file);
});

const result = await FileService.uploadDocuments(formData);

React 예시

import { useState } from "react";
import { FileService } from "@/services/FileService";

function FileUploader() {
  const [uploading, setUploading] = useState(false);

  const handleFileChange = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    setUploading(true);
    try {
      const formData = new FormData();
      formData.append("file", file);

      const result = await FileService.uploadAvatar(formData);
      console.log("Uploaded:", result.url);
    } catch (error) {
      console.error("Upload failed:", error);
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={handleFileChange}
        disabled={uploading}
      />
      {uploading && <p>Uploading...</p>}
    </div>
  );
}

TanStack Query 예시

import { useMutation } from "@tanstack/react-query";
import { FileService } from "@/services/FileService";

function useUploadFile() {
  return useMutation({
    mutationFn: (file: File) => {
      const formData = new FormData();
      formData.append("file", file);
      return FileService.uploadAvatar(formData);
    },
    onSuccess: (data) => {
      console.log("Upload success:", data);
    },
    onError: (error) => {
      console.error("Upload failed:", error);
    }
  });
}

function FileUploader() {
  const upload = useUploadFile();

  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (file) {
      upload.mutate(file);
    }
  };

  return (
    <div>
      <input
        type="file"
        onChange={handleFileChange}
        disabled={upload.isPending}
      />
      {upload.isPending && <p>Uploading...</p>}
      {upload.isSuccess && <p>Success: {upload.data.url}</p>}
      {upload.isError && <p>Error: {upload.error.message}</p>}
    </div>
  );
}

파일 검증

MIME 타입 검증

@upload()
async uploadImage() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  const allowedTypes = ["image/jpeg", "image/png", "image/gif"];
  if (!allowedTypes.includes(file.mimetype)) {
    throw new Error(`Invalid file type: ${file.mimetype}`);
  }

  return await this.processImage(file);
}

파일 크기 검증

@upload()
async uploadDocument() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  const maxSize = 10 * 1024 * 1024; // 10MB
  if (file.size > maxSize) {
    throw new Error("File too large");
  }

  return await this.saveDocument(file);
}

파일 확장자 검증

@upload()
async uploadFile() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  const allowedExtensions = ["jpg", "png", "pdf"];
  if (!file.extname || !allowedExtensions.includes(file.extname)) {
    throw new Error(`Invalid file extension: ${file.extname}`);
  }

  return await this.saveFile(file);
}

이미지 처리

Sharp 사용

import sharp from "sharp";

@upload()
async uploadAndResizeImage() {
  const { bufferedFiles } = Sonamu.getContext();
  const file = bufferedFiles?.[0];

  if (!file) {
    throw new Error("No file");
  }

  const buffer = file.buffer;

  // 이미지 리사이징
  const resized = await sharp(buffer)
    .resize(800, 600, { fit: "inside" })
    .jpeg({ quality: 80 })
    .toBuffer();

  // 썸네일 생성
  const thumbnail = await sharp(buffer)
    .resize(200, 200, { fit: "cover" })
    .jpeg({ quality: 70 })
    .toBuffer();

  // S3에 업로드 (Buffer를 직접 저장)
  const imageKey = `images/${Date.now()}.jpg`;
  await Sonamu.storage.use("s3").put(imageKey, resized);
  const imageUrl = await Sonamu.storage.use("s3").getUrl(imageKey);

  const thumbKey = `thumbnails/${Date.now()}.jpg`;
  await Sonamu.storage.use("s3").put(thumbKey, thumbnail);
  const thumbUrl = await Sonamu.storage.use("s3").getUrl(thumbKey);

  return { imageUrl, thumbUrl };
}

제약사항

1. @api 데코레이터 없이 독립 사용

@upload는 @api 데코레이터 없이 독립적으로 사용합니다:

// 올바른 사용법
@upload()
async uploadFile() {}

// 불필요 - @upload가 자동으로 API 설정
@api({ httpMethod: "POST" })
@upload()
async uploadFile() {}

2. httpMethod는 POST

@upload를 사용하면 자동으로 httpMethod: "POST"가 설정됩니다.

3. clients 자동 설정

@upload를 사용하면 clients 옵션이 자동으로 ["axios-multipart", "tanstack-mutation-multipart"]로 설정됩니다:

@upload()
async uploadFile() {
  // clients: ["axios-multipart", "tanstack-mutation-multipart"]
}

예시 모음

프로필 이미지
여러 파일 업로드
CSV 파일 처리
MD5 해시 기반 저장
Stream 모드 대용량

class UserModelClass extends BaseModelClass {
  @upload()
  @transactional()
  async uploadAvatar() {
    const { user, bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];

    if (!file) {
      throw new Error("No file uploaded");
    }

    // 이미지 타입 검증
    const allowedTypes = ["image/jpeg", "image/png", "image/webp"];
    if (!allowedTypes.includes(file.mimetype)) {
      throw new Error("Invalid image type");
    }

    // 이미지 처리
    const buffer = file.buffer;
    const processed = await sharp(buffer)
      .resize(300, 300, { fit: "cover" })
      .jpeg({ quality: 85 })
      .toBuffer();

    // S3 업로드
    const key = `avatars/${user.id}/${Date.now()}.jpg`;
    await Sonamu.storage.use("s3").put(key, processed);
    const url = await Sonamu.storage.use("s3").getUrl(key);

    // DB 업데이트
    const wdb = this.getDB("w");
    await wdb.table("users")
      .where("id", user.id)
      .update({ avatar_url: url });

    return { url };
  }
}

class DocumentModelClass extends BaseModelClass {
  @upload({ limits: { files: 10 } })
  @transactional()
  async uploadDocuments(params: { projectId: number }) {
    const { bufferedFiles } = Sonamu.getContext();
    const { projectId } = params;

    if (!bufferedFiles || bufferedFiles.length === 0) {
      throw new Error("No files uploaded");
    }

    const wdb = this.getDB("w");
    const results = [];

    for (const file of bufferedFiles) {
      // 파일 타입 검증
      const allowedTypes = [
        "application/pdf",
        "application/msword",
        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      ];

      if (!allowedTypes.includes(file.mimetype)) {
        throw new Error(`Invalid file type: ${file.filename}`);
      }

      // 파일 저장
      const md5 = await file.md5();
      const key = `documents/${projectId}/${md5}.${file.extname}`;
      const url = await file.saveToDisk("fs", key);

      // DB에 기록
      const doc = await wdb.table("documents").insert({
        project_id: projectId,
        filename: file.filename,
        url,
        size: file.size,
        mimetype: file.mimetype,
        created_at: new Date()
      }).returning("*");

      results.push(doc[0]);
    }

    return results;
  }
}

import Papa from "papaparse";

class ImportModelClass extends BaseModelClass {
  @upload()
  @transactional()
  async importUsers() {
    const { bufferedFiles } = Sonamu.getContext();
    const file = bufferedFiles?.[0];

    if (!file) {
      throw new Error("No file");
    }

    if (file.mimetype !== "text/csv") {
      throw new Error("CSV file required");
    }

    // CSV 파싱 (Buffer 직접 사용)
    const text = file.buffer.toString("utf-8");

    const parsed = Papa.parse<UserImportRow>(text, {
      header: true,
      skipEmptyLines: true
    });

    if (parsed.errors.length > 0) {
      throw new Error("CSV parsing failed");
    }

    // 데이터 검증 및 저장
    const wdb = this.getDB("w");
    const results = [];

    for (const row of parsed.data) {
      // 검증
      if (!row.email || !row.name) {
        throw new Error(`Invalid row: ${JSON.stringify(row)}`);
      }

      // 저장
      const user = await wdb.table("users")
        .insert({
          email: row.email,
          name: row.name,
          phone: row.phone || null,
          created_at: new Date()
        })
        .returning("*");

      results.push(user[0]);
    }

    return {
      imported: results.length,
      users: results
    };
  }
}

class FileModelClass extends BaseModelClass {
  @upload({ limits: { files: 10 } })
  async uploadWithDeduplication() {
    const { bufferedFiles } = Sonamu.getContext();

    if (!bufferedFiles || bufferedFiles.length === 0) {
      throw new Error("No files");
    }

    const results = [];
    for (const file of bufferedFiles) {
      // MD5 해시 계산
      const hash = await file.md5();

      // 해시로 파일 저장 (중복 방지)
      const ext = file.extname || "bin";
      const key = `uploads/${hash}.${ext}`;
      const url = await file.saveToDisk("fs", key);

      results.push({
        filename: file.filename,
        hash,
        url,
        size: file.size
      });
    }

    return results;
  }
}

class FileModelClass extends BaseModelClass {
  @upload({
    consume: "stream",
    destination: "s3",
    keyGenerator: (file) => `large-files/${Date.now()}-${file.filename}`,
    limits: { files: 3, fileSize: 100 * 1024 * 1024 }  // 100MB
  })
  async uploadLargeFiles() {
    const { uploadedFiles } = Sonamu.getContext();

    if (!uploadedFiles || uploadedFiles.length === 0) {
      throw new Error("No files");
    }

    // 파일은 이미 S3에 업로드된 상태
    return {
      files: uploadedFiles.map((file) => ({
        filename: file.filename,
        url: file.url,
        signedUrl: file.signedUrl,
        key: file.key,
        size: file.size,
      })),
    };
  }
}

참고 사항

@api 데코레이터와의 관계

@upload 데코레이터는 내부적으로 자동으로 API 엔드포인트를 생성합니다. 따라서 @api 데코레이터를 별도로 사용할 필요가 없습니다. 자동 설정되는 값:

httpMethod: "POST" (고정)
clients: ["axios-multipart", "tanstack-mutation-multipart"] (multipart 전용 클라이언트)
guards: @upload 옵션의 guards 값이 API에 전달됨
description: @upload 옵션의 description 값이 API에 전달됨

// @upload만 사용 (권장)
@upload()
async uploadFile() {
  // ...
}

// 불필요 - @api를 함께 사용할 필요 없음
@api({ httpMethod: "POST" })  // 불필요
@upload()
async uploadFile() {
  // ...
}

@upload는 파일 업로드에 최적화된 설정을 자동으로 적용하므로, @api 데코레이터를 추가로 사용할 필요가 없습니다.

다음 단계

@api

API 엔드포인트 만들기

@transactional

트랜잭션으로 안전하게 저장하기

Storage 드라이버

S3, Local 등 스토리지 사용하기

파일 처리

이미지/문서 처리 가이드

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

​업로드 모드

​Buffer 모드 (기본)

​BufferedFile 객체

​Stream 모드

​UploadedFile 객체

​옵션

​guards

​description

​limits

​파일 정보 확인

​파일 처리 (Buffer 모드)

​Buffer 접근

​파일 저장

​MD5 해시 계산

​스토리지 드라이버 사용

​다른 데코레이터와 함께 사용

​@transactional과 함께

​클라이언트 사용 (Web)

​Axios (단일 파일)

​Axios (여러 파일)

​React 예시

​TanStack Query 예시

​파일 검증

​MIME 타입 검증

​파일 크기 검증

​파일 확장자 검증

​이미지 처리

​Sharp 사용

​제약사항

​1. @api 데코레이터 없이 독립 사용

​2. httpMethod는 POST

​3. clients 자동 설정

​예시 모음

​참고 사항

​@api 데코레이터와의 관계

​다음 단계

@api

@transactional

Storage 드라이버

파일 처리

업로드 모드

Buffer 모드 (기본)

BufferedFile 객체

Stream 모드

UploadedFile 객체

옵션

guards

description

limits

파일 정보 확인

파일 처리 (Buffer 모드)

Buffer 접근

파일 저장

MD5 해시 계산

스토리지 드라이버 사용

다른 데코레이터와 함께 사용

@transactional과 함께

클라이언트 사용 (Web)

Axios (단일 파일)

Axios (여러 파일)

React 예시

TanStack Query 예시

파일 검증

MIME 타입 검증

파일 크기 검증

파일 확장자 검증

이미지 처리

Sharp 사용

제약사항

1. @api 데코레이터 없이 독립 사용

2. httpMethod는 POST

3. clients 자동 설정

예시 모음

참고 사항

@api 데코레이터와의 관계

다음 단계