NestJS 11 릴리스: 주요 변경점과 실무 업그레이드 가이드

Node.js 생태계에서 널리 쓰이는 백엔드 프레임워크 NestJS가 11 버전으로 올라섰습니다. 이번 메이저 업데이트는 프레임워크 내부 엔진을 최신 HTTP 라이브러리에 맞추고, 컨테이너 운영 환경에서 반복되던 보일러플레이트 코드를 줄이는 데 초점을 맞췄습니다.

가장 먼저 확인할 부분은 런타임 최소 요구 사양입니다. NestJS 11부터는 Node.js 16과 18 지원이 완전히 종료되었으며 최소 Node.js 20 이상을 요구합니다. 현재 LTS 버전 이상의 런타임을 사용하고 있지 않다면 환경부터 점검해야 합니다.

Express 5 기본 채택과 라우트 와일드카드 규칙 변경

기본 HTTP 플랫폼 어댑터가 Express 5로 전환되었습니다. 동시에 Fastify 5 지원도 공식화되었습니다. 이 변화로 가장 크게 영향을 받는 영역은 라우트 경로의 와일드카드 선언 방식입니다.

Express 5에서는 경로 매칭 알고리즘이 개선되면서 이름 없는 단독 별표 와일드카드 문법을 더 이상 허용하지 않습니다. 기존에 모든 경로를 가로채기 위해 작성했던 와일드카드 경로는 이제 이름을 지정한 형태로 바꿔야 합니다.

컨트롤러에서 하위 경로 전체를 처리하던 @Get('users/\*') 형태는 @Get('users/\*splat')처럼 명명된 매개변수 형태로 수정해야 합니다. 미들웨어 설정에서 흔히 작성하던 forRoutes('\*') 역시 forRoutes('\{\*splat\}')와 같은 명시적 와일드카드 문법으로 갱신해야 서버가 정상 구동됩니다. 기존 코드를 점검하지 않고 의존성만 올리면 부팅 시점에 라우트 매칭 에러가 발생할 수 있습니다.

기본 ConsoleLogger의 JSON 구조화 로깅 지원

도커 컨테이너나 쿠버네티스 환경으로 서버를 배포할 때 가장 번거로웠던 작업 중 하나는 JSON 로그 출력 설정이었습니다. 이전 버전까지는 Datadog이나 CloudWatch 같은 로그 수집기에 맞추기 위해 외부 로깅 라이브러리를 별도로 감싸거나 복잡한 커스텀 로거를 구현하는 경우가 많았습니다.

NestJS 11에서는 기본 로거인 ConsoleLogger에 네이티브 JSON 출력 옵션이 추가되었습니다. 복잡한 외부 의존성을 추가하지 않고도 옵션 하나로 직렬화된 로그를 생성할 수 있습니다.

NestJS 11 기준 main.ts 부트스트랩 코드는 다음과 같이 작성합니다.

typescript

import { NestFactory } from '@nestjs/core';
import { ConsoleLogger } from '@nestjs/common';
import { AppModule } from './app.module';

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

옵션을 활성화하면 타임스탬프, 로그 레벨, 컨텍스트, 메시지가 표준 JSON 포맷으로 표준 출력에 기록됩니다. 중첩된 객체나 배열, Map, Set 구조체도 훨씬 깔끔하게 포맷팅되어 로그 분석 파이프라인과의 연동이 쉬워집니다.

동적 모듈 로딩 구조 개선을 통한 부팅 속도 단축

대규모 프로젝트에서 동적 모듈을 다수 선언할 때 발생하던 부팅 지연 문제도 해결되었습니다. 이전 버전까지 프레임워크는 동적 모듈의 메타데이터 전체를 문자열로 직렬화하고 해시 값을 생성해 모듈의 고유성을 식별했습니다. 이 방식은 대형 설정 객체나 파일 데이터를 주입받는 동적 모듈이 늘어날수록 CPU 연산 비용과 메모리 소모를 키웠습니다.

NestJS 11은 메타데이터 해싱 대신 객체 참조를 직접 비교하는 방식으로 모듈 식별 로직을 간소화했습니다. 이에 따라 마이크로서비스나 모노레포 구조처럼 다수의 모듈을 조립해 띄우는 애플리케이션의 콜드 스타트 및 테스트 컨텍스트 초기화 속도가 크게 향상되었습니다.

지금 업그레이드해야 할까

Node.js 20 이상의 환경에서 컨테이너 기반으로 서비스를 운영하고 있고, 외부 로거 라이브러리 없이 표준화된 JSON 출력을 원한다면 이번 업그레이드는 충분한 가치가 있습니다. 라우트 경로에서 와일드카드를 과도하게 사용하지 않았다면 마이그레이션 작업도 비교적 수월합니다.

하지만 Express 4의 쿼리 스트링 파싱 동작에 강하게 의존하고 있거나 레거시 라우팅 규칙이 복잡하게 얽혀 있는 프로젝트라면 테스트 스위트를 먼저 보강해야 합니다. 특히 와일드카드 라우트와 미들웨어 매칭 경로를 전수 조사한 뒤 단계적으로 의존성을 올리는 방식을 추천합니다.

TrTrilon

Trilon Consulting - Announcing NestJS 11: What's New

Today I am excited to announce the official release of Nest 11: A progressive Node.js framework for building efficient and enterprise-grade, server-side applications.