Fastify 5 아키텍처 — 왜 Edge가 아닌 Node.js에 집중했을까

Maru

@maru

Fastify 5 아키텍처 — 왜 Edge가 아닌 Node.js에 집중했을까

Fastify 5 아키텍처 — 왜 Edge가 아닌 Node.js에 집중했을까

Fastify 5는 엣지나 서버리스 런타임으로 향하는 최근의 프레임워크 트렌드와 달리, Node.js 백엔드 고성능화라는 본연의 가치에 집중하는 정공법을 선택했습니다. 지원 엔진을 Node.js 20 버전 이상으로 명확히 제한하면서 오래된 감가상각 API와 아키텍처 부채를 과감하게 덜어냈습니다.

서버리스의 가벼움 대신 강력한 플러그인 격리 아키텍처와 스키마 기반 컴파일 성능을 극대화하는 영리한 노선을 택한 결과입니다. 대규모 트래픽을 처리하는 컨테이너 환경에서 Fastify 5가 여전히 최고의 선택인 이유와, 이를 관통하는 핵심 구조 및 설계 철학을 톺아봅니다.

고성능의 비밀: radix-tree 라우터와 Avvio 플러그인 그래프

Fastify가 기존 Node.js 프레임워크 대비 최대 3배 높은 처리량을 보여주는 핵심 동력은 전용 라우터와 독보적인 플러그인 아키텍처에 있습니다. 내장 라우팅 라이브러리인 find-my-way는 라딕스 트리 알고리즘을 활용해 등록된 경로가 아무리 많아져도 상수에 수렴하는 극도로 빠른 경로 검색 성능을 보장합니다.

또 다른 설계적 핵심은 비동기 플러그인 구동을 제어하는 아비오(Avvio) 라이브러리입니다. Fastify는 비순환 지향 그래프 형태로 플러그인의 관계와 로딩 순서를 제어하여 완벽한 스코프 캡슐화를 지원합니다. 특정 스코프 안에서 선언한 데코레이터나 생명주기 훅이 상위나 형제 스코프로 새어 나가지 않고 오직 하위 트리 내부로만 안전하게 격리되므로 부수 효과 없는 마이크로서비스 설계가 가능해집니다.

여기에 JSON 스키마 명세를 기반으로 직렬화 코드를 사전 빌드하는 fast-json-stringify 엔진이 더해집니다. 표준 JSON.stringify 호출 방식의 고질적인 런타임 오버헤드를 생략하고 성능 병목을 완전히 우회하여 하드웨어 자원을 극한까지 이끌어냅니다.

Type Provider: 빌드 단계 없는 실시간 스키마 타입 추론

Fastify는 별도의 빌드 단계나 스키마 코드 생성 없이 JSON 스키마를 TypeScript 타입으로 직접 매핑하는 Type Provider 패턴을 지원합니다. Zod나 TypeBox 같은 스키마 라이브러리를 사용해 런타임 유효성 검증 규칙을 선언하면, 컴파일러가 이를 이해하여 개발 시점에 완벽한 정적 타입으로 실시간 추론해 줍니다. 덕분에 코드와 검증 스키마가 일치하지 않아 발생하는 만성적인 동기화 오류를 근본적으로 예방할 수 있습니다.

가장 널리 쓰이는 fastify-type-provider-zod를 활용하면 초기 설정 이후 다음과 같이 라우트 핸들러에서 안전한 타입 추론을 바로 누릴 수 있습니다.

typescript
import Fastify from 'fastify';
import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
import type { ZodTypeProvider } from 'fastify-type-provider-zod';
import { z } from 'zod';

const server = Fastify().withTypeProvider<ZodTypeProvider>();
server.setValidatorCompiler(validatorCompiler);
server.setSerializerCompiler(serializerCompiler);

server.post('/users', {
  schema: {
    body: z.object({
      name: z.string().min(2),
      email: z.string().email()
    })
  }
}, async (req) => {
  const { name, email } = req.body; // 별도의 타입 단언 없이 자동 추론
  return { id: '1', name, email };
});

이렇게 정의된 스키마는 런타임 입력값 검증뿐만 아니라 OpenAPI 문서 규격으로도 연동되어 개발 생산성을 극대화합니다. 추가적인 빌드 컴파일 레이어를 우회하면서도 강력한 유효성 검증과 문서화 이점을 실시간으로 결합해 주는 고성능 설계의 핵심 축입니다.

Fastify 5 마이그레이션 마찰과 주요 변경점

Fastify 5로 메이저 버전을 올릴 때 가장 먼저 체감되는 파괴적 변경 사항은 스키마 정의 규격의 엄격화입니다. 이전 버전까지 편의를 위해 제공되던 jsonShorthand 옵션이 완전히 제거되었습니다. 이제 쿼리스트링, 요청 본문, 응답 등의 검증 스키마를 작성할 때 최상위에 명시적인 객체 타입과 속성을 선언하는 정식 JSON 스키마 규격을 반드시 준수해야 합니다.

Fastify 공식 마이그레이션 가이드에 따른 스키마 작성 방식의 변화는 다음과 같습니다.

javascript
// Fastify 4 (이전): 암묵적인 객체 래핑 허용
fastify.post('/user', {
  schema: {
    body: {
      name: { type: 'string' }
    }
  }
}, handler);

// Fastify 5 (이후): 명시적인 JSON 스키마 구조 필수
fastify.post('/user', {
  schema: {
    body: {
      type: 'object',
      properties: {
        name: { type: 'string' }
      },
      required: ['name']
    }
  }
}, handler);

네트워크 및 환경 정보를 다루는 API에도 표준을 준수하기 위한 변화가 생겼습니다. 기존에는 req.hostname 조회 시 포트 번호가 함께 포함되어 반환되었으나, Fastify 5부터는 Node.js 표준 URL 객체 규격에 맞춰 포트를 제외한 도메인명만 반환합니다. 기존의 호스트 및 포트 조합 정보가 필요하다면 req.host나 req.port를 명시적으로 조합해 사용해야 합니다.

또한 기본 유효성 검증 엔진인 Ajv의 시간 포맷 검증 규칙도 한층 더 엄격해졌습니다. 기존 'time'과 'date-time' 포맷은 반드시 표준 시간대 정보를 포함해야 검증을 통과하므로, 시간대 정보가 유동적인 환경이라면 'iso-time' 또는 'iso-date-time' 포맷으로 설정을 전환하는 마이그레이션 작업이 요구됩니다.

Node.js vs Edge 런타임: Fastify의 명확한 한계와 타겟 시장

Hono 같은 현대적인 프레임워크가 경량 엣지와 서버리스 환경을 장악하는 사이, Fastify는 오직 Node.js 런타임에 모든 역량을 집중했습니다. 이는 단순한 취향의 차이가 아니라, Fastify가 초고속 성능을 내기 위해 채택한 핵심 아키텍처가 엣지 환경의 제약 조건과 근본적으로 충돌하기 때문입니다.

가장 큰 걸림돌은 성능 최적화의 핵심인 JIT 스키마 컴파일러 설계입니다. Fastify는 Ajv와 fast-json-stringify를 활용해 런타임에 eval 함수로 스키마를 동적 컴파일하여 직렬화 속도를 일반 JSON 대비 몇 배 이상 끌어올립니다. 하지만 Cloudflare Workers나 Vercel Edge 같은 V8 아이솔레이트 격리 환경에서는 보안을 위해 동적 코드 평가가 완전히 금지되어 있어 실행 시점에 EvalError를 뱉으며 구동 자체가 불가능합니다.

또한 Fastify의 기본 로거인 Pino가 활용하는 멀티스레드 워커 아키텍처와 node:http 표준 모듈에 대한 깊은 의존성 역시 컨텍스트가 극도로 제한된 서버리스 환경에서는 오동작을 유발하는 요인이 됩니다. APIScout 분석에 따르면, 이러한 기술적 특성 때문에 Fastify는 전 세계 네트워크에 분산 배포되는 엣지 컴퓨팅보다는 컨테이너 기반 마이크로서비스나 독립 가상 서버에서 영속적으로 대규모 트래픽을 처리하는 전통적인 백엔드 아키텍처에 가장 적합합니다.

결국 Fastify는 모든 인프라 플랫폼을 어설프게 지원하느라 개성을 잃는 대신, Node.js 백엔드 인프라가 제공하는 자원을 극한까지 활용하는 정공법을 선택하여 독보적인 고성능 세그먼트를 구축하는 데 성공했습니다.

인프라 목적에 맞는 현실적인 프레임워크 선택

Fastify 5는 엣지 컴퓨팅 트렌드에 휩쓸리지 않고 Node.js 환경의 고성능 서버 구축이라는 핵심 가치에 집중한 프레임워크입니다. 전 세계 네트워크의 엣지 노드나 가벼운 서버리스 환경을 지향한다면 Hono와 같은 경량 프레임워크가 최적의 선택이 될 수 있지만, 컨테이너 클러스터나 가상 서버 환경에서 영속적인 백엔드 서비스를 안정적으로 운영해야 할 때는 판단 기준이 달라집니다. 이처럼 대규모 트래픽 처리가 중요한 영속 서버 환경에서는 강력한 타입 안정성과 압도적인 처리량을 모두 보장하는 Fastify 5와 Type Provider의 결합이 개발 생산성과 인프라 효율 측면에서 가장 매력적인 정답이 될 것입니다.

참고 링크

아직 댓글이 없습니다.