📌 NestJS 백엔드 개발: 기초부터 실전까지 - NestJS에서 파일 업로드 및 스트리밍 처리

📌 NestJS 백엔드 개발: 기초부터 실전까지 - NestJS에서 파일 업로드 및 스트리밍 처리

NestJS는 파일 업로드 및 스트리밍 기능을 제공하여 이미지, 동영상, 문서 등 다양한 파일을 API를 통해 처리할 수 있습니다.
이번 글에서는 @nestjs/platform-express와 Multer를 사용한 파일 업로드, 그리고 동영상 및 대용량 파일의 스트리밍 처리 방법을 소개합니다. 🚀

---

9.1 NestJS에서 파일 업로드를 위한 준비

✅ Multer 설치 (파일 업로드 미들웨어)

NestJS는 내부적으로 Multer를 사용해 파일 업로드를 처리합니다. 다음 명령어로 필요한 패키지를 설치합니다.

npm install @nestjs/platform-express multer
npm install --save-dev @types/multer

---

9.2 단일 파일 업로드 구현하기

📂 users.controller.ts

import { Controller, Post, UploadedFile, UseInterceptors } from '@nestjs/common';
import { FileInterceptor } from '@nestjs/platform-express';
import { diskStorage } from 'multer';
import { extname } from 'path';

@Controller('users')
export class UsersController {
  @Post('upload')
  @UseInterceptors(FileInterceptor('file', {
    storage: diskStorage({
      destination: './uploads',
      filename: (req, file, callback) => {
        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1e9);
        const ext = extname(file.originalname);
        callback(null, `${file.fieldname}-${uniqueSuffix}${ext}`);
      },
    }),
  }))
  uploadFile(@UploadedFile() file: Express.Multer.File) {
    return {
      originalname: file.originalname,
      filename: file.filename,
      size: file.size,
    };
  }
}

✅ @UseInterceptors(FileInterceptor)를 사용하여 단일 파일 업로드 처리
✅ diskStorage를 이용해 업로드 경로와 파일명 커스터마이징
✅ 업로드된 파일은 ./uploads 디렉터리에 저장됨

---

9.3 다중 파일 업로드 처리

📂 users.controller.ts

import { UploadedFiles, UseInterceptors } from '@nestjs/common';
import { FilesInterceptor } from '@nestjs/platform-express';

@Post('uploads')
@UseInterceptors(FilesInterceptor('files', 10)) // 최대 10개까지 업로드
uploadMultipleFiles(@UploadedFiles() files: Array<Express.Multer.File>) {
  return files.map(file => ({
    originalname: file.originalname,
    filename: file.filename,
  }));
}

✅ FilesInterceptor를 사용해 다중 파일 처리 가능
✅ @UploadedFiles()를 통해 파일 배열을 받을 수 있음

---

9.4 파일 업로드 시 필터링 및 제한 설정

@UseInterceptors(FileInterceptor('file', {
  fileFilter: (req, file, cb) => {
    if (!file.mimetype.match(/\/(jpg|jpeg|png)$/)) {
      return cb(new Error('Only image files are allowed!'), false);
    }
    cb(null, true);
  },
  limits: {
    fileSize: 5 * 1024 * 1024, // 5MB 제한
  },
}))

✅ 특정 MIME 타입만 허용 (예: 이미지 파일만)
✅ 업로드 파일 크기 제한 가능

---

9.5 업로드된 파일 제공 (Static Serve)

반응형

@nestjs/serve-static 패키지를 사용하면 정적 파일 경로로 업로드된 파일을 접근할 수 있습니다.

npm install @nestjs/serve-static

📂 app.module.ts

import { ServeStaticModule } from '@nestjs/serve-static';
import { join } from 'path';

@Module({
  imports: [
    ServeStaticModule.forRoot({
      rootPath: join(__dirname, '..', 'uploads'),
      serveRoot: '/uploads',
    }),
  ],
})
export class AppModule {}

✅ http://localhost:3000/uploads/파일명으로 파일 접근 가능

---

9.6 파일 스트리밍 처리 (동영상/대용량 파일)

동영상, 오디오, 대용량 파일은 일반 다운로드 대신 스트리밍 방식으로 처리하는 것이 효율적입니다.

📂 stream.controller.ts

import { Controller, Get, Res, Req } from '@nestjs/common';
import { createReadStream, statSync } from 'fs';
import { join } from 'path';
import { Response, Request } from 'express';

@Controller('stream')
export class StreamController {
  @Get('video')
  streamVideo(@Req() req: Request, @Res() res: Response) {
    const videoPath = join(__dirname, '..', 'uploads', 'sample.mp4');
    const stat = statSync(videoPath);
    const fileSize = stat.size;
    const range = req.headers.range;

    if (range) {
      const parts = range.replace(/bytes=/, '').split('-');
      const start = parseInt(parts[0], 10);
      const end = parts[1] ? parseInt(parts[1], 10) : fileSize - 1;
      const chunksize = end - start + 1;
      const file = createReadStream(videoPath, { start, end });

      res.writeHead(206, {
        'Content-Range': `bytes ${start}-${end}/${fileSize}`,
        'Accept-Ranges': 'bytes',
        'Content-Length': chunksize,
        'Content-Type': 'video/mp4',
      });

      file.pipe(res);
    } else {
      res.writeHead(200, {
        'Content-Length': fileSize,
        'Content-Type': 'video/mp4',
      });

      createReadStream(videoPath).pipe(res);
    }
  }
}

✅ Range 헤더를 이용해 부분 스트리밍 지원
✅ 클라이언트(브라우저)는 비디오를 점진적으로 다운로드하며 재생 가능

---

9.7 파일 업로드 및 스트리밍 실전 팁

✔ 파일 이름 중복 방지를 위해 UUID 또는 타임스탬프 활용
✔ 업로드된 파일에 접근 권한을 설정하여 보안 유지
✔ S3 또는 클라우드 저장소 연동으로 확장 가능
✔ 파일 업로드/삭제/다운로드를 RESTful하게 설계하기

💡 NestJS의 Express 기반 구조 덕분에 Multer 및 파일 스트리밍 처리가 매우 유연합니다.

---

9.8 결론: NestJS에서의 파일 업로드 및 스트리밍 정리

✅ Multer를 사용한 단일 및 다중 파일 업로드 지원
✅ 파일 타입 제한 및 업로드 용량 제한 설정 가능
✅ ServeStaticModule로 업로드된 파일 정적 제공
✅ Stream 방식으로 동영상 등 대용량 파일 효율적으로 처리

다음 글에서는 **"NestJS와 WebSocket을 활용한 실시간 기능 구현"**을 다룹니다. 🚀

---

🔍 다음 글 예고: NestJS와 WebSocket을 활용한 실시간 기능 구현

📌 다음 편: 10. NestJS WebSocket 실시간 처리