🐈
NestJS 치트시트

TypeScript 기반 엔터프라이즈 Node.js 백엔드 프레임워크 완벽 가이드: 필수 사전 설치 요건, 모듈·컨트롤러·서비스 아키텍처 및 의존성 주입(DI), 요청 처리 생명주기(Middleware·Guard·Interceptor·Pipe·Filter), DTO 유효성 검증, TypeORM/Prisma 연동, JWT 인증 및 프로덕션 운영 체크리스트
#nestjs#typescript#nodejs#backend#dependency-injection#typeorm#prisma#jwt#swagger#rest-api최종 업데이트: 2026-10-08
NestJS 치트시트 핵심 명령어 및 실전 가이드

## 1. 필수 사전 설치 요건 & 개발 환경 구성 (Prerequisites)

NestJS는 TypeScript를 기본 언어로 채택한 진보된 Node.js 엔터프라이즈 백엔드 프레임워크입니다. Spring Boot와 유사한 객체지향 프로그래밍(OOP), 함수형 프로그래밍(FP), 함수 반응형 프로그래밍(FRP) 요소와 강력한 의존성 주입(DI) 시스템을 제공합니다.

### 🟢 1. Node.js 런타임 버전 & 버전 관리자
NestJS는 **Node.js 18.x, 20.x, 22.x LTS 이상** 환경을 필요로 합니다.

```bash
# 1. Node.js 버전 확인 (v18.0.0 이상 필수, 권장: v20.x 또는 v22.x LTS)
node -v
npm -v

# 2. Node 버전 관리자(fnm 또는 nvm)를 통한 최신 LTS 설치 (Windows / macOS / Linux)
# fnm 사용 시 (초고속 권장)
fnm install --lts
fnm use lts-latest

# nvm 사용 시
nvm install --lts
nvm use --lts
```

### 🛠️ 2. NestJS CLI 설치 및 새 프로젝트 생성
공식 Nest CLI를 전역으로 설치하거나, `npx`로 바로 스캐폴딩할 수 있습니다:

```bash
# 옵션 A: Nest CLI 전역 설치 (권장)
npm install -g @nestjs/cli
nest --version

# 새 프로젝트 스캐폴딩 생성 (패키지 매니저는 npm/pnpm/yarn 중 선택)
nest new my-nest-app --package-manager npm
cd my-nest-app

# 옵션 B: CLI 전역 설치 없이 npx로 즉시 생성
npx @nestjs/cli new my-nest-app --package-manager npm
cd my-nest-app
```

### ⚙️ 3. 필수 TypeScript 컴파일러 설정 (`tsconfig.json`)
NestJS는 데코레이터(`@Controller`, `@Injectable` 등)와 리플렉션 메타데이터를 핵심으로 사용하므로, `tsconfig.json`에 다음 옵션이 반드시 활성화되어 있어야 합니다:

```json
{
  "compilerOptions": {
    "module": "commonjs",
    "declaration": true,
    "removeComments": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
    "allowSyntheticDefaultImports": true,
    "target": "ES2021",
    "sourceMap": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "incremental": true,
    "skipLibCheck": true,
    "strictNullChecks": false,
    "noImplicitAny": false,
    "strictBindCallApply": false,
    "forceConsistentCasingInFileNames": false,
    "noFallthroughCasesInSwitch": false
  }
}
```

### 📦 4. 필수 의존성 패키지 설치
검증 파이프 및 환경변수 관리에 필수적인 라이브러리를 설치합니다:

```bash
# DTO 유효성 검사 및 객체 변환 라이브러리
npm install class-validator class-transformer

# 환경변수(.env) 설정 모듈
npm install @nestjs/config

# 개발 서버 실행 (코드 변경 시 자동 핫 리로드)
npm run start:dev
```

---

## 2. NestJS 핵심 개념 & 요청 처리 생명주기 (Mental Model)

NestJS로 들어오는 모든 HTTP 요청은 일관되고 체계적인 파이프라인 단계를 거쳐 처리됩니다.

### 🔄 HTTP 요청 처리 생명주기 (Request Lifecycle)
```text
[HTTP 클라이언트 요청]
        │
        ▼
 1. Middleware (로깅, 세션, CORS, Body 파싱 등 전역/라우트 미들웨어)
        │
        ▼
 2. Guards (인증 토큰 검증, Role/권한 인가 체크: canActivate())
        │
        ▼
 3. Interceptors (Pre-Controller: 핸들러 진입 전 시간 측정, 요청 변형)
        │
        ▼
 4. Pipes (DTO 스키마 검증: class-validator, 타입 형변환: ParseIntPipe)
        │
        ▼
 5. Controller (핸들러 함수 라우팅: @Get, @Post, 요청 객체 추출)
        │
        ▼
 6. Service / Provider (비즈니스 로직 연산, DB 쿼리, 외부 API 호출)
        │
        ▼
 7. Interceptors (Post-Controller: RxJS pipe로 응답 구조 표준화, 캐싱)
        │
        ▼
 8. Exception Filters (처리 중 발생한 예외를 일관된 JSON 에러 형식으로 변환)
        │
        ▼
[클라이언트로 HTTP 응답 전송]
```

### 🧩 3대 핵심 아키텍처 구성요소
1. **Modules (`@Module`)**: 애플리케이션 구조를 구성하는 경계 단위. Controller와 Provider를 묶고, 다른 모듈과 결합합니다.
2. **Controllers (`@Controller`)**: 들어오는 클라이언트 HTTP 요청을 수신하고, 경로 매핑 후 적절한 Service로 위임합니다.
3. **Providers / Services (`@Injectable`)**: 비즈니스 로직을 수행하며, NestJS IoC(제어의 역전) 컨테이너에 의해 자동으로 생성자 주입(DI)됩니다.

---

## 3. [초보자 1단계] 헬로월드: 최소 동작 예제

Nest CLI의 복잡한 보일러플레이트 없이, 단일 파일 수준의 최소 코드로 NestJS의 구동 원리를 즉시 파악할 수 있는 예제입니다.

### 📄 파일 작성: `src/main-standalone.ts`
```typescript
import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { Module, Controller, Get, Param, ParseIntPipe } from '@nestjs/common';

// 1. Controller 정의: HTTP 요청을 처리하는 핸들러
@Controller('api')
class HelloController {
  @Get('hello')
  getHello(): { message: string; timestamp: string } {
    return {
      message: 'Hello, NestJS World!',
      timestamp: new Date().toISOString(),
    };
  }

  @Get('users/:id')
  getUser(@Param('id', ParseIntPipe) id: number): { userId: number; status: string } {
    return {
      userId: id,
      status: 'active',
    };
  }
}

// 2. Module 정의: 컨트롤러와 의존성 프로바이더를 묶는 컨테이너
@Module({
  controllers: [HelloController],
})
class HelloAppModule {}

// 3. 부트스트랩 함수: Nest 애플리케이션 인스턴스 생성 및 포트 리스닝
async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(HelloAppModule);
  const PORT = 3000;
  await app.listen(PORT);
  console.log(`🚀 NestJS 서버가 구동되었습니다: http://localhost:${PORT}/api/hello`);
}

bootstrap();
```

### 💻 실행 및 동작 확인
```bash
# ts-node로 직접 실행
npx ts-node src/main-standalone.ts

# 콘솔 출력 확인:
# 🚀 NestJS 서버가 구동되었습니다: http://localhost:3000/api/hello

# 다른 터미널에서 curl 요청 테스트:
curl http://localhost:3000/api/hello
# 응답 결과:
# {"message":"Hello, NestJS World!","timestamp":"2026-10-08T11:55:00.000Z"}

curl http://localhost:3000/api/users/42
# 응답 결과:
# {"userId":42,"status":"active"}
```

---

## 4. [초보자 2단계] 핵심 기능 & 모듈 아키텍처

실무 NestJS 프로젝트의 기본 표준인 컨트롤러, 서비스, DTO 검증 파이프 및 모듈 시스템 구조입니다.

### 🕹️ 1. DTO & Validation Pipe (입력값 유효성 검증)
클라이언트의 요청 바디(Body)를 안전하게 검증하는 DTO(Data Transfer Object) 클래스입니다.

```typescript
// src/posts/dto/create-post.dto.ts
import { IsString, IsNotEmpty, MinLength, MaxLength, IsOptional, IsBoolean } from 'class-validator';

export class CreatePostDto {
  @IsString({ message: '제목은 문자열이어야 합니다.' })
  @IsNotEmpty({ message: '제목은 필수 입력 항목입니다.' })
  @MinLength(2, { message: '제목은 최소 2자 이상이어야 합니다.' })
  @MaxLength(100, { message: '제목은 최대 100자까지 가능합니다.' })
  readonly title: string;

  @IsString({ message: '내용은 문자열이어야 합니다.' })
  @IsNotEmpty({ message: '내용은 필수 입력 항목입니다.' })
  readonly content: string;

  @IsBoolean()
  @IsOptional()
  readonly isPublished?: boolean = false;
}
```

### ⚙️ 2. Service & 의존성 주입 (Dependency Injection)
`@Injectable()` 데코레이터가 붙은 클래스는 Nest IoC 컨테이너가 인스턴스 생명주기(싱글톤 기본값)를 관리합니다.

```typescript
// src/posts/posts.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { CreatePostDto } from './dto/create-post.dto';

export interface PostItem {
  id: number;
  title: string;
  content: string;
  isPublished: boolean;
  createdAt: Date;
}

@Injectable()
export class PostsService {
  private posts: PostItem[] = [
    {
      id: 1,
      title: 'NestJS 시작하기',
      content: 'NestJS 아키텍처와 DI 시스템 익히기',
      isPublished: true,
      createdAt: new Date(),
    },
  ];
  private idCounter = 2;

  findAll(): PostItem[] {
    return this.posts;
  }

  findOne(id: number): PostItem {
    const post = this.posts.find((p) => p.id === id);
    if (!post) {
      throw new NotFoundException(`ID가 ${id}인 게시글을 찾을 수 없습니다.`);
    }
    return post;
  }

  create(dto: CreatePostDto): PostItem {
    const newPost: PostItem = {
      id: this.idCounter++,
      title: dto.title,
      content: dto.content,
      isPublished: dto.isPublished ?? false,
      createdAt: new Date(),
    };
    this.posts.push(newPost);
    return newPost;
  }

  remove(id: number): { success: boolean; deletedId: number } {
    this.findOne(id); // 없으면 NotFoundException 발생
    this.posts = this.posts.filter((p) => p.id !== id);
    return { success: true, deletedId: id };
  }
}
```

### 🌐 3. Controller & HTTP 라우팅
경로 파라미터(`@Param`), 쿼리스트링(`@Query`), 본문(`@Body`), 상태코드(`@HttpCode`)를 처리합니다.

```typescript
// src/posts/posts.controller.ts
import {
  Controller,
  Get,
  Post,
  Delete,
  Body,
  Param,
  ParseIntPipe,
  HttpCode,
  HttpStatus,
} from '@nestjs/common';
import { PostsService, PostItem } from './posts.service';
import { CreatePostDto } from './dto/create-post.dto';

@Controller('posts')
export class PostsController {
  // 생성자 주입(Constructor Injection): IoC 컨테이너가 PostsService 싱글톤 주입
  constructor(private readonly postsService: PostsService) {}

  @Get()
  getAllPosts(): PostItem[] {
    return this.postsService.findAll();
  }

  @Get(':id')
  getPostById(@Param('id', ParseIntPipe) id: number): PostItem {
    return this.postsService.findOne(id);
  }

  @Post()
  @HttpCode(HttpStatus.CREATED)
  createPost(@Body() dto: CreatePostDto): PostItem {
    return this.postsService.create(dto);
  }

  @Delete(':id')
  deletePost(@Param('id', ParseIntPipe) id: number): { success: boolean; deletedId: number } {
    return this.postsService.remove(id);
  }
}
```

### 📦 4. 모듈 분리 (`@Module`) 및 전역 파이프 등록
기능 단위 모듈로 분리하고 `AppModule`에 통합합니다.

```typescript
// src/posts/posts.module.ts
import { Module } from '@nestjs/common';
import { PostsController } from './posts.controller';
import { PostsService } from './posts.service';

@Module({
  controllers: [PostsController],
  providers: [PostsService],
  exports: [PostsService], // 다른 모듈에서 PostsService를 주입받을 수 있도록 노출
})
export class PostsModule {}
```

```typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { PostsModule } from './posts/posts.module';

@Module({
  imports: [PostsModule],
})
export class AppModule {}
```

```typescript
// src/main.ts (진입점: 전역 ValidationPipe 활성화)
import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule);

  // 전역 유효성 검사 파이프 등록 (매우 중요)
  app.useGlobalPipes(
    new ValidationPipe({
      whitelist: true,            // DTO에 정의되지 않은 임의의 속성은 자동 제거
      forbidNonWhitelisted: true, // DTO에 정의되지 않은 필드 전달 시 400 Bad Request 에러 반환
      transform: true,            // 요청 페이로드를 DTO 클래스 인스턴스로 자동 변환
    }),
  );

  await app.listen(3000);
  console.log('Server running on http://localhost:3000');
}
bootstrap();
```

---

## 5. [초보자 3단계] 실무 응용 패턴 & 미들웨어 파이프라인

실무 프로덕션 환경에서 필수적으로 사용되는 설정 모듈, 예외 필터, 인터셉터, 인증 가드, Swagger 문서화 패턴입니다.

### 🔑 1. ConfigModule & 환경변수 관리 (`@nestjs/config`)
```bash
npm install @nestjs/config
```

```typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,                         // 모든 모듈에서 ConfigService 주입 가능
      envFilePath: `.env.${process.env.NODE_ENV || 'development'}`,
    }),
  ],
})
export class AppModule {}
```

```typescript
// 서비스에서 환경변수 사용 예시
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';

@Injectable()
export class DatabaseConfigService {
  constructor(private readonly configService: ConfigService) {}

  get databaseUrl(): string {
    return this.configService.get<string>('DATABASE_URL', 'localhost:5432');
  }
}
```

### 🛡️ 2. 전역 예외 필터 (HttpExceptionFilter)
백엔드 전체에서 발생하는 에러 응답 포맷을 일관된 JSON 스키마로 표준화합니다.

```typescript
// src/common/filters/http-exception.filter.ts
import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpException,
  HttpStatus,
  Logger,
} from '@nestjs/common';
import { Request, Response } from 'express';

@Catch()
export class AllExceptionsFilter implements ExceptionFilter {
  private readonly logger = new Logger(AllExceptionsFilter.name);

  catch(exception: unknown, host: ArgumentsHost): void {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
    const request = ctx.getRequest<Request>();

    const status =
      exception instanceof HttpException
        ? exception.getStatus()
        : HttpStatus.INTERNAL_SERVER_ERROR;

    const message =
      exception instanceof HttpException
        ? exception.getResponse()
        : 'Internal server error';

    const errorResponse = {
      statusCode: status,
      timestamp: new Date().toISOString(),
      path: request.url,
      method: request.method,
      error: typeof message === 'object' ? message : { message },
    };

    this.logger.error(`[${request.method}] ${request.url} - Status: ${status}`);

    response.status(status).json(errorResponse);
  }
}
```

### ⏱️ 3. 로깅 & 실행시간 측정 인터셉터 (LoggingInterceptor)
요청과 응답의 실행 시간을 RxJS의 `tap` 연산자로 계측합니다.

```typescript
// src/common/interceptors/logging.interceptor.ts
import {
  Injectable,
  NestInterceptor,
  ExecutionContext,
  CallHandler,
  Logger,
} from '@nestjs/common';
import { Observable } from 'rxjs';
import { tap } from 'rxjs/operators';

@Injectable()
export class LoggingInterceptor implements NestInterceptor {
  private readonly logger = new Logger('HTTP');

  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
    const request = context.switchToHttp().getRequest();
    const { method, url } = request;
    const now = Date.now();

    return next.handle().pipe(
      tap(() => {
        const response = context.switchToHttp().getResponse();
        const delay = Date.now() - now;
        this.logger.log(`[${method}] ${url} ${response.statusCode} +${delay}ms`);
      }),
    );
  }
}
```

### 🔐 4. 인증 & 인가 가드 (Auth Guard)
요청 헤더의 Authorization 토큰을 검증하여 핸들러 접근을 제어합니다.

```typescript
// src/common/guards/auth.guard.ts
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';
import { Observable } from 'rxjs';

@Injectable()
export class SimpleAuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean | Promise<boolean> | Observable<boolean> {
    const request = context.switchToHttp().getRequest();
    const authHeader = request.headers['authorization'];

    if (!authHeader || !authHeader.startsWith('Bearer ')) {
      throw new UnauthorizedException('인증 토큰이 누락되었거나 유효하지 않습니다.');
    }

    const token = authHeader.split(' ')[1];
    // 토큰 검증 로직 (실무: jwtService.verify(token))
    if (token !== 'secret-lucky-token') {
      throw new UnauthorizedException('유효하지 않은 토큰입니다.');
    }

    // 검증된 사용자 정보를 request 객체에 주입
    request.user = { userId: 1, username: 'lucky_developer' };
    return true;
  }
}

// 컨트롤러 적용 예시:
// @UseGuards(SimpleAuthGuard)
// @Get('protected')
// getProtectedData(@Req() req) { return req.user; }
```

### 📖 5. Swagger (OpenAPI) 문서 자동 생성
```bash
npm install @nestjs/swagger
```

```typescript
// src/main.ts 에서 Swagger 설정 등록
import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  const config = new DocumentBuilder()
    .setTitle('LuckyTechWorld API')
    .setDescription('NestJS 고성능 엔터프라이즈 REST API 명세서')
    .setVersion('1.0.0')
    .addBearerAuth()
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api/docs', app, document);

  await app.listen(3000);
  console.log('Swagger UI: http://localhost:3000/api/docs');
}
bootstrap();
```

---

## 6. 실무 주의사항 & 프로덕션 체크리스트

### ⚠️ 1. 초보자가 가장 흔히 겪는 실수 & 해결법

| 번호 | 흔한 에러 및 증상 | 근본 원인 | 해결 방법 |
| :---: | :--- | :--- | :--- |
| **1** | `Nest can't resolve dependencies of the XService (?)` | 의존하는 Service가 속한 모듈에서 `exports`하지 않았거나, 대상 모듈의 `imports` 배열에 추가하지 않음 | 공급자 모듈의 `@Module({ exports: [XService] })` 확인 후 소비자 모듈의 `imports: [XModule]` 추가 |
| **2** | 순환 참조 에러 (`A ➔ B ➔ A`) | 두 모듈 또는 서비스가 서로를 직접 주입하고 있음 | 생성자 주입 시 `@Inject(forwardRef(() => OtherService))` 및 `imports: [forwardRef(() => OtherModule)]` 사용 |
| **3** | DTO 검증 데코레이터가 전혀 동작하지 않음 | `main.ts`에 `app.useGlobalPipes(new ValidationPipe())` 미등록 | `main.ts` 부트스트랩 함수 내 전역 `ValidationPipe` 추가 |
| **4** | 데코레이터 메타데이터 에러 (`Unable to resolve signature...`) | `tsconfig.json` 컴파일러 플래그 누락 | `experimentalDecorators: true`, `emitDecoratorMetadata: true` 설정 확인 |

### 🚀 2. 프로덕션 성능 & 보안 체크리스트

1. **Fastify 어댑터 전환 (초고속 성능 필요 시)**:
   기본 Express 어댑터 대신 Fastify를 사용하면 초당 처리량(RPS)이 최대 2배까지 향상됩니다.
   ```bash
   npm install @nestjs/platform-fastify
   ```
   ```typescript
   import { FastifyAdapter, NestFastifyApplication } from '@nestjs/platform-fastify';
   const app = await NestFactory.create<NestFastifyApplication>(
     AppModule,
     new FastifyAdapter(),
   );
   ```
2. **보안 헤더 & CORS**:
   ```bash
   npm install helmet
   ```
   ```typescript
   import helmet from 'helmet';
   app.use(helmet());
   app.enableCors({ origin: ['https://luckytech.world'], credentials: true });
   ```
3. **디도스/남용 방지 Rate Limiting**:
   ```bash
   npm install @nestjs/throttler
   ```
4. **Graceful Shutdown (우아한 종료 보장)**:
   Kubernetes 컨테이너 롤링 배포 시 진행 중인 요청의 유실을 방지합니다:
   ```typescript
   // main.ts
   app.enableShutdownHooks();
   ```

### ⚡ 3. Nest CLI 핵심 단축 명령어 모음

| 작업 목적 | 전체 명령어 | 단축 명령어 | 자동 생성 결과물 |
| :--- | :--- | :--- | :--- |
| **프로젝트 생성** | `nest new <이름>` | `nest new <이름>` | 전체 프로젝트 구조 스캐폴딩 |
| **CRUD 전체 리소스** | `nest generate resource <이름>` | `nest g res <이름>` | Controller + Service + Module + DTO + Entity 일괄 생성 |
| **모듈 생성** | `nest generate module <이름>` | `nest g mo <이름>` | `xxx.module.ts` 생성 및 AppModule 등록 |
| **컨트롤러 생성** | `nest generate controller <이름>` | `nest g co <이름>` | `xxx.controller.ts` 생성 및 Module 등록 |
| **서비스 생성** | `nest generate service <이름>` | `nest g s <이름>` | `xxx.service.ts` 생성 및 Module 등록 |
| **가드 생성** | `nest generate guard <이름>` | `nest g gu <이름>` | `xxx.guard.ts` 생성 |
| **인터셉터 생성** | `nest generate interceptor <이름>` | `nest g in <이름>` | `xxx.interceptor.ts` 생성 |
| **예외 필터 생성** | `nest generate filter <이름>` | `nest g f <이름>` | `xxx.filter.ts` 생성 |
| **미들웨어 생성** | `nest generate middleware <이름>` | `nest g mi <이름>` | `xxx.middleware.ts` 생성 |
💬
NestJS 치트시트

의견 및 질문

댓글 수정

댓글 삭제
