Zod 스키마 하나로 TypeScript 타입 추론, 런타임 검증, OpenAPI 문서를 한 번에 해결하는 Fastify 5 서버 구조

import {
  ZodTypeProvider,           // 타입 레벨 연결 — withTypeProvider<ZodTypeProvider>()
  validatorCompiler,         // 런타임 검증
  serializerCompiler,        // 응답 직렬화
  jsonSchemaTransform,       // 라우트별 Zod → JSON Schema 변환
  jsonSchemaTransformObject, // 앱 전체 스펙 변환
  FastifyPluginAsyncZod,     // 플러그인 타입 헬퍼 (withTypeProvider 대체)
} from "@fastify/type-provider-zod";

flowchart LR
  Z["Zod 스키마"]
  Z --> T["TypeScript 타입 추론"]
  Z --> V["런타임 검증"]
  Z --> O["OpenAPI 스펙 생성"]
  T --> DX["타입 안전한 핸들러"]
  V --> E["400 에러 자동 응답"]
  O --> S["Swagger UI 렌더링"]

// transform이 있는 스키마 예시
const DateSchema = z.object({
  createdAt: z.string().transform((s) => new Date(s)),
});
 
// Zod v3: 응답 직렬화 시 z.input 기준 → string 타입 기대
// Zod v4: 응답 직렬화 시 z.output 기준 → Date 타입 기대
// → v4에서 serializerCompiler가 Date 객체를 응답에 그대로 넣으려 하면
//   JSON 직렬화 과정에서 타입 불일치 오류 발생

flowchart TD
  Start["REST API + TypeScript 시작"]
  Q1{"클라이언트도 TypeScript 전용?"}
  Q2{"OpenAPI 문서가 필요한가?"}
  Q3{"엣지 런타임이 필요한가?"}
 
  Start --> Q1
  Q1 -->|"예"| tRPC["tRPC\n최강 타입 안전성"]
  Q1 -->|"다양한 클라이언트"| Q2
  Q2 -->|"불필요"| Q3
  Q3 -->|"예"| Hono["Hono + Zod\n경량 엣지 친화적"]
  Q3 -->|"아니오"| Fastify["Fastify 5 + type-provider-zod\n성능 + 문서 자동화"]
  Q2 -->|"필요, 코드 생성 허용"| NestJS["NestJS + nestjs-swagger\n엔터프라이즈 구조"]

import Fastify from "fastify";
import {
  serializerCompiler,
  validatorCompiler,
  ZodTypeProvider,
  jsonSchemaTransform,
  jsonSchemaTransformObject,
} from "@fastify/type-provider-zod";
import fastifySwagger from "@fastify/swagger";
import fastifySwaggerUI from "@fastify/swagger-ui";
 
const app = Fastify({ logger: true });
 
// 핵심 1: 두 컴파일러 모두 등록
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);
 
// 핵심 2: Swagger 플러그인은 라우트 등록 전에 먼저
await app.register(fastifySwagger, {
  openapi: {
    openapi: "3.0.3",
    info: { title: "My API", version: "1.0.0" },
  },
  transform: jsonSchemaTransform,
  transformObject: jsonSchemaTransformObject,
});
 
await app.register(fastifySwaggerUI, { routePrefix: "/docs" });

import { z } from "zod";
 
app.withTypeProvider<ZodTypeProvider>().route({
  method: "POST",
  url: "/users",
  schema: {
    tags: ["users"],
    summary: "사용자 생성",
    body: z.object({
      name: z.string().min(2, "이름은 2자 이상이어야 합니다"),
      email: z.email(),  // Zod v4 스타일: z.string().email() 대신 사용
      role: z.enum(["admin", "viewer"]).default("viewer"),
    }),
    response: {
      201: z.object({
        id: z.number(),
        name: z.string(),
        email: z.email(),
        role: z.enum(["admin", "viewer"]),
      }),
    },
  },
  handler: async (req, reply) => {
    // req.body는 { name: string, email: string, role: "admin" | "viewer" }
    // IDE 자동완성 + 타입 체크 모두 작동
    const user = await createUser(req.body);
    return reply.status(201).send(user);
  },
});

sequenceDiagram
  participant C as 클라이언트
  participant F as Fastify
  participant V as validatorCompiler
  participant H as 핸들러
  participant S as serializerCompiler
 
  C->>F: POST /users 요청
  F->>V: body를 Zod 스키마로 파싱
  alt 검증 실패
    V-->>C: 400 Bad Request 자동 응답
  else 검증 성공
    V->>H: 타입 추론된 req.body 전달
    H->>S: reply.send 호출
    S-->>C: JSON 직렬화 응답
  end

app.withTypeProvider<ZodTypeProvider>().get(
  "/users/:id",
  {
    schema: {
      params: z.object({
        id: z.coerce.number().int().positive(),
        // URL 파라미터는 항상 문자열로 들어옴.
        // z.coerce.number()가 Number("123") → 123 변환을 처리해준다.
      }),
      querystring: z.object({
        // z.coerce.boolean()은 쓰지 않는다.
        // Boolean("false") === true이므로 ?includeDeleted=false가 true로 파싱된다.
        includeDeleted: z.preprocess(
          (v) => (v === undefined ? undefined : v === "true"),
          z.boolean().optional().default(false)
        ),
      }),
      response: {
        200: z.object({
          id: z.number(),
          name: z.string(),
          role: z.enum(["admin", "viewer"]),
        }),
      },
    },
  },
  async (req, reply) => {
    // req.params.id는 number, req.query.includeDeleted는 boolean
    const user = await findUser(req.params.id, req.query.includeDeleted);
    return reply.send(user);
  }
);

import { z } from "zod";
 
const UserSchema = z
  .object({
    id: z.number(),
    name: z.string(),
    email: z.email(),
  })
  .meta({ id: "User" });
// .meta({ id: "User" })를 붙이면 OpenAPI 문서에서
// $ref: '#/components/schemas/User'로 참조됨
 
app.withTypeProvider<ZodTypeProvider>().get(
  "/users/:id",
  {
    schema: {
      params: z.object({ id: z.coerce.number() }),
      response: { 200: UserSchema },
    },
  },
  async (req, reply) => {
    const user = await findUser(req.params.id);
    return reply.send(user);
  }
);

// routes/users.ts
import { FastifyPluginAsyncZod } from "@fastify/type-provider-zod";
import { z } from "zod";
 
const usersPlugin: FastifyPluginAsyncZod = async (app) => {
  // withTypeProvider 없이도 ZodTypeProvider가 적용된 상태
  app.get(
    "/",
    {
      schema: {
        response: { 200: z.array(UserSchema) },
      },
    },
    async (req, reply) => {
      return reply.send(await getAllUsers());
    }
  );
 
  app.post(
    "/",
    {
      schema: {
        body: z.object({
          name: z.string().min(2),
          email: z.email(),
        }),
        response: { 201: UserSchema },
      },
    },
    async (req, reply) => {
      const user = await createUser(req.body);
      return reply.status(201).send(user);
    }
  );
};
 
export default usersPlugin;

// app.ts
await app.register(usersPlugin, { prefix: "/users" });

// 빠지기 쉬운 실수
app.setValidatorCompiler(validatorCompiler);
// serializerCompiler 누락!
 
// 올바른 형태
app.setValidatorCompiler(validatorCompiler);
app.setSerializerCompiler(serializerCompiler);