모두싸인 팀이 NestJS v8에서 v10으로 메이저 버전 업데이트를 진행하면서 마주친 주요 변경 사항과 해결 방법을 정리한 글이다. createParamDecorator API 변경부터 Terminus 모듈 구조 변경, HttpException 타입 강화까지 실제 마이그레이션 과정을 코드 레벨에서 다룬다.
핵심 포인트- createParamDecorator의 제네릭 타입이 any에서 ExecutionContext로 변경되어 기존 코드에서 타입 오류 발생
- Terminus 헬스체크 모듈의 구조가 Service 기반에서 Controller 기반으로 전환
- HttpException의 message 필드 타입이 any에서 string으로 강화되어 객체 전달 패턴 수정 필요
- 토큰 분리를 위한 providerMapper 함수 도입으로 의존성 주입 구조 개선
- v6/v10 이중 환경 지원을 위해 jest moduleNameMapper 설정으로 버전별 테스트 분기 처리
상세 정리- NestJS 메이저 버전 업그레이드는 단순 npm install이 아니라 각 의존 패키지(Terminus, HttpException, 데코레이터 API)의 변경 사항을 개별 확인해야 한다
- createParamDecorator<unknown, ExecutionContext> 패턴으로 타입 시그니처 명시가 필요
- Terminus v10에서는 HealthCheckService를 모듈 외부에서 직접 주입받는 구조가 Controller로 이동
- HttpException을 오브젝트로 던지는 패턴은 더 이상 동작하지 않아 string 직렬화 처리 추가 필요
- jest 설정에서 moduleNameMapper를 활용해 v6/v10 경로를 동적으로 분기하면 마이그레이션 중 테스트 안정성 확보 가능
- 의존성 주입 토큰 충돌을 방지하기 위해 providerMapper 유틸리티 함수로 중복 토큰 분리
- Breaking change 목록을 NestJS 공식 마이그레이션 가이드에서 먼저 확인하고, 타입 오류를 빌드 단계에서 조기 발견하는 것이 핵심
- 실서비스 적용 전 feature 브랜치에서 jest 전 스위트를 돌리며 regression 확인하는 절차 필수
왜 읽나NestJS 메이저 버전 업그레이드를 준비 중인 팀에 실제 함정과 코드 수준 해결책을 제공한다.