pile·
백엔드·모두싸인모두싸인·

NestJS v10 업데이트의 여정

모두싸인 팀이 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 메이저 버전 업그레이드를 준비 중인 팀에 실제 함정과 코드 수준 해결책을 제공한다.
모두싸인
모두싸인 블로그
원문은 여기서 이어서 읽을 수 있어요
원문 읽기
읽음 (0)

이 글과 비슷한

  1. 백엔드·twilio-engTwilio Engineering·

    Programmable Messaging에서 Verify API로 마이그레이션하기

    Twilio의 Programmable Messaging API로 자체 OTP 솔루션을 운영하던 서비스가 Verify API로 전환하는 방법을 코드 예시와 함께 설명한다. Verify는 OTP 전송·검증을 위한 전용 API로, 전화번호 구매, 토큰 생성, DB 저장·만료 관리를 내부에서 처리해 개발자가 직접 구현할 코드를 크게 줄인다.

    요약 이어보기
    #authentication#twilio#sms+2
  2. 백엔드·포스타입포스타입·

    포스타입이 개인화 추천을 하는 방법 2부

    포스타입 백엔드 엔지니어가 벡터 기반 개인화 추천 시스템을 실제 운영하며 맞닥뜨린 성능 장애와 용량 문제를 해결한 과정을 담은 2부다. 수백만 개의 벡터 KNN 검색이 피크 시간대에 전체 Elasticsearch 검색 성능을 흔드는 문제부터 클러스터 OOM 사태까지, 쿼리 최적화와 인프라 분리 두 가지 경로로 근본 해결에 이른다.

    요약 이어보기
    #elasticsearch#vector-search#recommendation-system+2
  3. 백엔드·포스타입포스타입·

    포스타입이 개인화 추천을 하는 방법 1부

    포스타입이 태그 기반 추천의 한계를 극복하고 벡터 임베딩 기반 개인화 추천 시스템을 구축한 과정을 담은 1부다. 유사한 콘텐츠가 다른 용어를 쓰거나 동일한 태그가 전혀 다른 톤의 콘텐츠를 가리키는 문제를 임베딩 벡터로 해결하고, OpenSearch의 HNSW ANN 검색으로 수백만 벡터를 실시간 검색하는 시스템을 구축해 구매율 15% 향상을 달성했다.

    요약 이어보기
    #opensearch#vector-search#recommendation-system+2