Fastify v6 미리보기 — V8 직렬화와 createPlugin이 바꾸는 백엔드 설계

Fastify가 최근 v6 프리릴리즈를 공개하며 고성능 백엔드 프레임워크의 핵심 동작 메커니즘을 전면 개편했습니다. 이번 업데이트는 오랫동안 성능을 견인하던 직렬화 라이브러리를 덜어내고 V8 엔진 네이티브 직렬화를 도입하는 등 대대적인 구조 단순화를 목표로 합니다. 특히 대규모 TypeScript 모노레포 환경에서 발생하던 전역 타입 오염 문제를 해결하기 위한 새로운 플러그인 설계 표준도 함께 제시합니다.

1. fast-json-stringify 탈피와 V8 네이티브 직렬화로의 전환

Fastify v6 아키텍처의 가장 큰 변화는 오랫동안 고성능의 핵심 축이었던 fast-json-stringify 라이브러리를 의존성에서 제거하고, Node.js V8 엔진의 네이티브 JSON 직렬화 방식으로 전환했다는 점입니다. 이 결정은 복잡한 스키마 컴파일 레이어를 덜어내어 내부 프레임워크의 유지보수성을 개선하고, 비약적으로 발전한 최신 V8 엔진의 객체 최적화 성능을 그대로 활용하기 위함입니다.

하지만 이 변화는 백엔드 개발자에게 단순한 성능 지표 이상의 설계적 고민을 던집니다. 기존 Fastify는 정의된 응답 스키마를 기반으로 직렬화 단계에서 스키마에 존재하지 않는 추가 필드를 자동으로 제거해 주었습니다. 일종의 보안 필터 역할을 했던 셈입니다. 네이티브 직렬화로 전환되면서 이러한 자동 필터링 동작이 제거되었기 때문에, 개발자가 의도하지 않은 민감한 데이터나 데이터베이스의 추가 필드가 응답 페이로드에 그대로 노출될 위험이 생겼습니다.

이러한 보안 공백을 방지하려면 데이터 진입 단계부터 안전장치를 걸어두어야 합니다. 스키마 유효성 검증을 담당하는 Ajv 설정에서 추가 필드를 자동으로 제거해 주는 removeAdditional 옵션을 엄격하게 활성화하는 설계가 권장됩니다. 프레임워크가 보장해 주던 암묵적인 필터링 영역이 명시적인 스키마 제어 영역으로 넘어왔기 때문에, 이제는 응답과 입력 스키마 정의를 한층 더 꼼꼼하게 관리해야 합니다.

2. 전역 오염 없는 타입 안전성: createPlugin의 등장

TypeScript 모노레포 환경에서 가장 큰 골칫거리였던 전역 타입 오염 문제가 Fastify v6와 fastify-plugin v6.0.0의 등장으로 마침내 해결되었습니다. 기존에는 데코레이터나 플러그인 타입을 확장할 때 전역 선언 병합 방식에 의존해야 했기 때문에, 플러그인을 주입하지 않은 다른 하위 서비스의 타입까지 함께 왜곡되는 문제가 빈번하게 일어났습니다.

새로 도입된 createPlugin 헬퍼는 이러한 전역 타입 오염 문제를 완벽하게 차단합니다. 전역 네임스페이스를 강제로 확장하는 방식 대신, 플러그인이 실제로 등록된 스코프 안에서만 커스텀 데코레이터와 컨텍스트 타입을 격리하여 하위 라우터 트리로 안전하게 전파합니다.

여기에 TypeBox 기반의 타입 프로바이더를 조합하면, 별도의 전역 타입 선언 파일 없이도 컴파일러 수준에서 안전한 요청 타입 추론을 완성할 수 있습니다.

이 패턴을 적용하면 대규모 프로젝트 내의 여러 마이크로서비스가 서로의 타입 선언에 전혀 영향을 주지 않습니다. 개발자가 애플리케이션 빌드 중 실제로 주입하지 않은 모듈이나 데코레이터에 잘못 접근하는 논리적 실수를 컴파일 타임에 즉시 잡아낼 수 있습니다.

3. LogController 분리와 구형 FSTDEP 경고의 예외 없는 에러화

Fastify v6에서는 서버 인스턴스의 전역 로깅 옵션을 조정하던 최상위 속성들이 완전히 제거되었습니다. 기존 버전에서 사용하던 disableRequestLogging이나 requestIdLogLabel 같은 전역 옵션을 더 이상 사용할 수 없습니다. 대신 완전히 독립적으로 설계된 LogController 클래스를 직접 인스턴스화하여 서버 옵션의 logController 속성에 주입하는 구조로 전면 개편되었습니다.

이러한 변화는 서버 설정 플래그가 무분별하게 늘어나는 것을 방지하고 로깅 관심사를 깔끔하게 격리합니다. 다음은 변경 전후의 로깅 설정 구성입니다.

과거 버전에서 하위 호환성을 지키기 위해 터미널 경고만 출력하던 레거시 코드들도 한층 엄격하게 정리되었습니다. v5에서 FSTDEP022부터 FSTDEP025에 해당하는 경고 메시지만 띄우던 옵션들은 v6에 이르러 서버 구동 자체를 즉시 중단시키는 치명적인 에러로 변환되었습니다. 설정 오류가 있는 애플리케이션이 프로덕션 환경에 배포되는 것을 초기 단계에서 차단하여 안정성을 확보하려는 조치입니다.

4. NestJS 호환성 경고와 플러그인 생태계 전환 현황

Fastify v6 도입을 검토할 때 가장 먼저 확인해야 할 부분은 상위 프레임워크 생태계의 호환성입니다. 특히 NestJS 기반 아키텍처를 운영하고 있다면 v6로의 즉각적인 마이그레이션은 지양해야 합니다. 현재 NestJS 공식 어댑터인 @nestjs/platform-fastify는 Fastify v5 버전에 고정되어 있어 인터페이스 수준에서 완벽히 동기화되지 않은 상태입니다.

만약 패키지 매니저 설정을 통해 NestJS 프로젝트에 Fastify v6를 강제로 오버라이드하여 주입할 경우, 애플리케이션 부트스트랩 단계에서 심각한 의존성 충돌이나 라우팅 바인딩 실패로 서버 구동 자체가 불가능해질 수 있습니다. NestJS 개발팀이 내부 설정 구조를 정비하며 대비하고 있지만, 공식 어댑터가 v6를 완전히 지원하기 전까지는 프로덕션 환경에서 수동 전환을 시도하지 않는 것이 안전합니다.

반면 프레임워크 추상화 레이어를 걷어내고 순수 Fastify로 구축된 독립형 프로젝트라면 이전 일정을 훨씬 유연하게 가져갈 수 있습니다. 핵심 에코시스템 플러그인인 @fastify/swagger-ui와 @fastify/autoload 등은 이미 v6 지원 체계를 안정적으로 갖추었습니다. 따라서 프레임워크 의존성이 없는 마이크로서비스나 독립형 API 서버부터 점진적으로 v6 전환을 계획하는 방식을 추천합니다.

5. 마치며: 다가올 Fastify v6 시대를 준비하는 로드맵

Fastify v6 정식 버전이 출시되면 기존 v5는 곧바로 6개월 동안 보안 업데이트만 받는 상태로 전환됩니다. 따라서 전역 타입 오염을 차단하는 createPlugin 도입과 LogController 기반의 로깅 구조 개편 등 핵심 아키텍처 변화에 미리 대비해야 합니다. 지금부터 타입 선언 병합을 줄이고 TypeBox 중심의 통합 검증 체계를 미리 구축해 둔다면 다가올 메이저 업데이트에 손쉽게 대응할 수 있습니다.

참고 링크