Fastify v5 업데이트, Node.js 20 요구사항과 주요 변경점 정리

Fastify가 다섯 번째 메이저 버전인 v5를 공식 릴리스했습니다. 높은 처리량과 가벼운 아키텍처로 Node.js 생태계에서 널리 쓰이는 웹 프레임워크인 만큼, 이번 판올림이 기존 코드에 어떤 영향을 주는지 살펴볼 필요가 있습니다.

Fastify v5는 레거시 런타임 호환성을 과감하게 털어내고 최신 Node.js 환경의 표준 진단 도구와 완전한 스키마 정의를 중심으로 프레임워크를 정돈했습니다.

런타임 최소 사양의 상향: Node.js 20 이상 필수

Fastify v5의 가장 큰 변화는 최소 구동 환경입니다. Node.js 18 지원을 완전히 중단하고 Node.js 20 이상 버전을 필수로 요구합니다. v4의 장기 지원 기간이 마무리 단계에 접어들면서, 런타임의 최신 성능 개선 사항과 내장 진단 도구를 적극 활용하기 위한 결정입니다.

프로젝트를 Fastify v5로 올리기 전에 서버 환경이나 컨테이너 베이스 이미지가 Node.js 20 이상인지 확인해야 합니다. 하위 버전의 Node.js에서 구동을 시도하면 설치 혹은 실행 단계에서 엔진 호환성 경고나 구동 실패를 만나게 됩니다.

jsonShorthand 제거와 엄격해진 JSON Schema

라우트 유효성 검사에서 비표준 단축 표기법이었던 jsonShorthand 지원이 완전히 삭제되었습니다. Fastify v4까지는 쿼리나 본문 스키마를 선언할 때 최상위 type: 'object'를 생략하는 축약 표기를 일부 허용했습니다. v5부터는 스키마 사양을 명확히 따르는 완전한 JSON Schema 객체만 허용합니다.

Fastify v5 공식 문서 기준으로 스키마는 다음과 같이 최상위 타입을 명시적으로 작성해야 합니다.

typescript

// Fastify v5 기준 라우트 스키마 정의
fastify.post('/items', {
  schema: {
    body: {
      type: 'object',
      required: ['name'],
      properties: {
        name: { type: 'string' }
      }
    }
  }
}, async (request, reply) => {
  return { ok: true, name: request.body.name };
});

기존 프로젝트에 축약형 스키마가 남아 있다면 Fastify 인스턴스 초기화 시점에 컴파일 에러가 발생하므로, 라우트 정의 전반의 스키마 구조를 점검해야 합니다.

node:diagnostics_channel 통합과 관측성 개선

애플리케이션 모니터링 영역에서는 Node.js 내장 진단 채널인 node:diagnostics\_channel 연동이 정식으로 반영되었습니다. 별도 서드파티 플러그인이나 몽키 패칭 없이도 HTTP 요청의 수신, 라우팅, 응답 종료 등 수명 주기 전반을 표준 진단 이벤트로 구독할 수 있습니다.

OpenTelemetry 연동 라이브러리나 분산 추적 시스템을 구축할 때 오버헤드를 낮추면서 정밀한 측정값을 확보할 수 있게 되었습니다.

응답 시간 측정 및 네트워크 프로퍼티 정리

사용 빈도가 높았던 일부 헬퍼 메서드와 프로퍼티도 표준화되었습니다. 응답 경과 시간을 밀리초 단위로 가져오던 reply.getResponseTime() 메서드가 제거되고 reply.elapsedTime 게터 프로퍼티로 대체되었습니다.

오래된 Node.js HTTP 객체 잔재였던 request.connection 접근 역시 제거되었습니다. 소켓 정보가 필요하다면 request.socket 또는 request.raw.socket을 직접 참조해야 합니다. 내부 라우터인 find-my-way와의 정합성을 높이기 위해 fastify.hasRoute()의 경로 매칭 규칙도 라우터의 실제 동작 방식과 동일하게 통일되었습니다.

도입 판단과 시작 방법

신규 Node.js 서비스를 준비 중이라면 Node.js 20 또는 최신 LTS 환경 위에서 Fastify v5로 시작하는 구성이 자연스럽습니다. 기본 구조가 더 엄격해졌기 때문에 설계 단계부터 표준 JSON Schema를 적용해 타입 안정성을 확보하기 좋습니다.

운영 중인 Fastify v4 프로젝트를 마이그레이션할 때는 두 가지를 순서대로 확인하면 충분합니다. 실행 서버의 Node.js 20 업데이트 여부를 점검하고, 라우트 정의에 남아 있는 축약형 스키마와 reply.getResponseTime() 호출부를 검색해 수정하는 것으로 전환 작업을 마무리할 수 있습니다.

FaFastify

Fastify v5 Migration Guide

Fastify is a web framework highly focused on providing the best developer experience with the least overhead and a powerful plugin architecture.