NestJS 11 출시: 주요 변경 사항과 마이그레이션 가이드

2025년 1월 22일, NestJS 11 버전이 공식적으로 출시되었습니다. 이번 업데이트는 성능 향상, 새로운 기능 추가, Node.js 최신 버전 지원 등으로 개발자들에게 더욱 강력한 도구를 제공합니다. 이 글에서는 주요 변경 사항과 마이그레이션 가이드를 정리했습니다.

---

주요 변경 사항

1. Node.js 지원 버전 변경

NestJS 11은 Node.js v20 이상을 요구합니다. Node.js v16 및 v18에 대한 지원이 중단되었으므로, 기존 애플리케이션은 반드시 Node.js를 최신 버전으로 업그레이드해야 합니다. 최신 Node.js 기능과 성능 최적화를 활용할 수 있어, 더 안정적이고 효율적인 애플리케이션 운영이 가능합니다.

# Node.js 버전 확인
node -v

# Node.js 최신 버전 설치 (예: nvm 사용)
nvm install 20
nvm use 20

2. Express 및 Fastify 업데이트

• Express v5: Express v5로 업그레이드되며, 경로 매칭 알고리즘이 변경되었습니다. 예를 들어, 기존의 @Get('users/*')는 @Get('users/*splat')로 변경해야 합니다. 이는 Express의 새로운 정규식 지원 방식 때문입니다. 이러한 개선으로 경로 정의가 더욱 명확해지고, 유지보수성을 크게 높일 수 있습니다.

import { Controller, Get } from '@nestjs/common';

@Controller('users')
export class UsersController {
  // 기존 방식
  @Get('/*')
  handleWildcard() {
    return 'Wildcard route';
  }

  // Express v5 방식
  @Get('/*splat')
  handleWildcardNew() {
    return 'Updated wildcard route';
  }
}

• Fastify v5: Fastify v5가 기본적으로 통합되어 성능과 유연성이 향상되었습니다. Fastify의 빠른 요청 처리 능력을 활용하여 더 높은 확장성과 효율적인 리소스 관리를 기대할 수 있습니다.

3. 로거 개선

• JSON 형식의 로그를 기본 지원하여 컨테이너 환경에서 로그를 분석하기 쉬워졌습니다.
• 깊이 중첩된 객체와 배열의 포맷팅이 개선되었고, 로그 접두사를 커스터마이징할 수 있습니다. 이러한 개선으로 디버깅 및 로그 관리가 더욱 직관적이고 효과적으로 변했습니다.

import { Logger } from '@nestjs/common';

const logger = new Logger('MyApp');
logger.log({ event: 'user_created', user: { id: 1, name: 'John Doe' } });

4. 마이크로서비스 트랜스포터 개선

• 새로운 unwrap, status, on 메서드가 도입되어 클라이언트와 서버의 마이크로서비스 트랜스포터에서 더 많은 작업을 처리할 수 있습니다.
• 클라이언트 상태를 실시간으로 모니터링할 수 있는 스트림(status)이 추가되었습니다. 이를 통해 서비스 상태를 한눈에 파악하고 문제를 빠르게 진단할 수 있습니다.

const client = app.connectMicroservice({ transport: Transport.NATS });
client.status().subscribe(status => console.log('Client status:', status));

5. 라이프사이클 훅 실행 순서 변경

종료 라이프사이클 훅(OnModuleDestroy, BeforeApplicationShutdown, OnApplicationShutdown)이 초기화 순서의 역순으로 실행됩니다. 이를 통해 리소스 정리가 더욱 직관적으로 이루어지며, 애플리케이션 종료 시 예측 가능한 순서로 작업이 처리됩니다.

---

마이그레이션 가이드

NestJS 11로 마이그레이션하려면 다음 단계를 따라야 합니다.

1. 패키지 업그레이드

npm-check-updates(ncu)와 같은 도구를 사용하여 패키지를 최신 버전으로 업그레이드하세요. 최신 버전의 의존성을 적용하면 보안 강화 및 성능 최적화 효과를 기대할 수 있습니다.

ncu -u
npm install

2. Express 및 Fastify 관련 변경

• Express v5에서 와일드카드 경로 매칭 규칙이 변경되었으므로, 모든 경로를 점검하고 필요한 경우 수정하세요.
• Fastify v5로 전환된 경우, 문서를 Fastify v5 공식 문서를 참고하여 변경 사항을 반영하세요. 이를 통해 애플리케이션의 안정성과 성능이 한층 더 향상됩니다.

3. 모듈 해상도 개선 사항 적용

NestJS 11에서는 모듈 해상도 알고리즘이 변경되었습니다. 동적 모듈을 여러 모듈에서 공유하려면 변수에 할당하여 재사용하세요. 이로 인해 모듈 간 의존성이 더 명확해지고, 유지보수가 용이해집니다.

import { DynamicModule } from '@nestjs/common';

const SharedModule: DynamicModule = {
  module: SharedModule,
  global: true,
};

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

4. Reflector 및 CacheModule 업데이트

• Reflector 클래스는 메타데이터 작업의 타입 안정성과 성능이 향상되었습니다.
• @nestjs/cache-manager 패키지에서 외부 스토어 구성이 변경되었습니다. Redis를 사용하는 경우 KeyvRedis 어댑터를 적용해야 합니다. 개선된 캐싱 메커니즘은 데이터 처리 속도를 높이고, 안정적인 캐싱 환경을 제공합니다.

import { CacheModule } from '@nestjs/cache-manager';
import * as KeyvRedis from 'keyv-redis';

@Module({
  imports: [
    CacheModule.register({
      store: new KeyvRedis('redis://localhost:6379'),
    }),
  ],
})
export class AppModule {}

5. ConfigModule 변경 사항

ConfigModule에서 내부 설정이 환경 변수보다 우선 처리되며, 새로운 validatePredefined 옵션이 추가되었습니다. 이전의 ignoreEnvVars는 제거되었습니다. 이 변경은 설정의 일관성을 유지하고 예측 가능한 환경 구성을 가능하게 합니다.

import { ConfigModule } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot({
      validatePredefined: true,
    }),
  ],
})
export class AppModule {}

---

결론

NestJS 11은 성능과 유연성을 향상시키는 여러 개선 사항을 도입했습니다. 특히 Node.js 최신 버전을 지원하고 Express 및 Fastify의 새로운 기능을 통합함으로써 개발자 경험을 한층 더 발전시켰습니다. 마이그레이션 과정에서 주요 변경 사항을 숙지하고 가이드를 따라 새로운 기능을 활용하세요.

NestJS 11에 대한 더 자세한 내용은 공식 문서, 릴리스 노트, 그리고 NestJS 11 발표 블로그를 참고하세요.