NestJS 11 업데이트 살펴보기

 

2025년 1월 22일 NestJS 11 버전 업데이트가 공지되었습니다. 

 

로거 기능 추가, 마이크로서비스 트랜스포터 개선, 어플리케이션 속도 향상, Express / Fastify v5 지원 등이 이번 업데이트의 메인 포인트입니다.

 

1. 로거 업그레이드

NestJS 의 기본 로거인 ConsoleLogger 가 이제 중첩 객체, 배열에 대한 더 나은 포맷팅을 제공하고 Map / Set 자료구조를 지원합니다. 또한 이번 로거 업데이트에 JSON 로깅 기능이 추가되었습니다. 이제 JSON 형식으로 로그를 출력할 수 있습니다. 

 

아래 구성을 통해 JSON 형식 로깅을 설정할 수 있습니다. 

const app = await NestFactory.create(AppModule, {
  logger: new ConsoleLogger({
    json: true,
  }),
});

json : true 설정 시

 

또한 아래와 같이 colors 옵션을 통해 로컬 개발 중 가독성을 높이는 방법도 지원합니다. 

const app = await NestFactory.create(AppModule, {
  logger: new ConsoleLogger({
    json: true,
    colors: true,
  }),
});

colors : true 설정 시

 

로거의 변경 사항은 이 PR을 통해 자세히 확인 가능합니다.

 

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

NestJS 11버전에선  NATS, Kafka, Redis 같은 마이크로서비스 트랜스포터 부분이 크게 개선되었습니다. 

 

2-1. unwrap 메소드로 네이티브 클라이언트 직접 제어

이제 NestJS 가 커버하고 있는 NATS, Kafka 와 같은 클라이언트를 직접 컨트롤 할 수 있습니다. 

 

아래 코드와 같이 NATS의 클라이언트를 가져와 내부 상태를 확인하거나 원래 API를 사용할 수 있습니다.

import { NatsConnection } from 'nats';

// 마이크로서비스 연결
const serviceRef = app.connectMicroservice({
  transport: Transport.NATS,
  options: {
    // NATS 연결 옵션
  },
});

// 원래 NATS 클라이언트 가져오기
const connection = serviceRef.unwrap<NatsConnection>();

// 클라이언트 정보 출력
console.log(connection.info);

 

물론 unwrap 메소드는 NATS 뿐 아니라 Kafka, Redis 와 같이 다른 트랜스포터에서도 사용 가능합니다. 

 

2-2. on 메소드로 클라이언트 이벤트 감지

on 메소드를 통해 이벤트를 감지하고 그에 맞는 처리를 할 수 있습니다. 

const serviceRef = app.connectMicroservice({
  transport: Transport.NATS,
  options: {
    // NATS 연결 옵션
  },
});

// 연결 종료 이벤트 감지
serviceRef.on<NatsEvents>('disconnect', () => {
  console.log('클라이언트가 연결을 끊었습니다.');
});

 

2-3. Status 스트림으로 실시간 상태 확인

status 스트림을 통해 클라이언트의 상태를 실시간으로 감지가 가능합니다. 

const serviceRef = app.connectMicroservice({
  transport: Transport.NATS,
  options: {
    // NATS 연결 옵션
  },
});

// 상태 변화 감지
serviceRef.status.subscribe((status) => {
  console.log('현재 상태:', status);
});

 

발생하는 상태(status) 는 총 4개가 있습니다.

 

connecting -> 연결 중

connected -> 연결 완료

disconnected -> 연결 끊어짐

reconnecting -> 다시 연결 시도 중

 

연결 상태를 기반으로 실시간 모니터링이 가능하며 빠르게 대응이 가능하겠네요.

 

자세한 디테일은 이 공식문서 링크를 통해 확인하실 수 있습니다. 

 

3. 어플리케이션 시작 속도 향상

NestJS 11 버전에서는 동적 모듈을 구분하기 위해 메타 데이터를 해쉬로 변환하고 이로 고유 키를 생성하던 방식 대신 객체 참조를 통해 모듈 키를 관리합니다. 

 

기존 방식은 입력 데이터가 클수록 해시 생성이 느려지는 문제가 있었는데, 객체 참조를 사용하여 불필요한 연산을 줄여 결과적으로 어플리케이션 시작 속도가 비약적으로 빨라졌다고 합니다. 

 

이로 인해 같은 동적 모듈을 여러 번 불러올 때 동작 방식이 달라졌습니다. 

 

기존엔  동일한 동적 모듈을 여러번 임포트할 때 단일 인스턴스로 병합되었지만 이젠 별도의 인스턴스로 취급합니다. 동일한 동적 모듈을 여러 번 불러오는 경우, 어플리케이션 전체에서 하나의 인스턴스가 사용되지 않을 수도 있으니 주의해야겠습니다. 

 

4. Express / Fastify V5 지원

NestJS 11 버전부터 Express 와 Fastify 의 V5 를 지원합니다. 

 

Fastify v5로 업데이트 시 문제 없이 기존 코드 그대로 사용 가능하나, Express v5 로 업데이트 시 경로 라우팅 코드에서 문제가 발생할 수 있습니다.

 

그 이유는 Express V5의 경로 매칭 방식이 변경되었기 때문입니다. 

 

4-1. Express V5에서는 라우팅 경로에서 * 와일드카드는 단독으로 사용 불가능하며 *splat, *wildcard 와 같이 이름을 붙여야 합니다. 

// ❌ Express v5에서 권장되지 않는 방식
@Get('users/*')
findAll() {
  return '이제 이렇게 하면 안 돼요!';
}

// ✅ 올바른 방식 (와일드카드에 이름 추가)
@Get('users/*splat')
findAll() {
  return '이제 이 방식으로 사용해야 해요!';
}

 

4-2. ? 기호 대신 {} 를 사용해야 합니다.

// ❌ 기존 방식
@Get('/files/:name?.:ext')
findFile() {}

// ✅ Express v5 방식
@Get('/files/:name{.:ext}')
findFile() {}

 

4-3. 경로 라우팅에서 정규식(RegExp) 패턴을 지원하지 않습니다.

// ❌ RegExp 사용 불가
@Get('/product/:id(\\d+)') // 숫자만 허용하는 정규식
findProduct() {}

// ✅ 정규식 없이 처리
@Get('/product/:id') 
findProduct(@Param('id') id: number) {
  if (isNaN(id)) throw new BadRequestException('숫자만 입력 가능');
}

 

Express V5로의 마이그레이션 가이드는 이 링크를 통해 자세히 확인할 수 있습니다. 

 

 

여기까지가 NestJS 11버전의 메인 업데이트 사항입니다. 

 

자잘한 업데이트 사항도 있으니 공식 업데이트 안내문을 통해 추가적으로 확인해보시면 좋을 것 같습니다.