Fastify v5 + TypeBox로 TypeScript REST API 구축하기

// Express 방식: 같은 정보가 세 군데에 흩어져 있습니다
interface CreateUserDto {            // 1. TypeScript 타입
  name: string
  email: string
  role: 'admin' | 'editor' | 'viewer'
}
 
app.post('/users',
  body('email').isEmail(),           // 2. 런타임 검증
  body('name').notEmpty(),
  async (req, res) => {
    const errors = validationResult(req)
    if (!errors.isEmpty()) return res.status(400).json({ errors: errors.array() })
 
    // 3. Swagger 문서는 별도 JSDoc 또는 YAML 파일에서 관리
    const user = req.body as CreateUserDto
    res.json(await createUser(user))
  }
)

import { Type, Static } from '@sinclair/typebox'
 
const UserSchema = Type.Object({
  id: Type.Number(),
  name: Type.String({ minLength: 1 }),
  email: Type.String({ format: 'email' })
})
 
// 별도 interface 선언 없이 타입이 자동으로 추론됩니다
type User = Static<typeof UserSchema>
// => { id: number; name: string; email: string }

npm install fastify @sinclair/typebox @fastify/type-provider-typebox
npm install @fastify/swagger @fastify/swagger-ui
npm install -D typescript @types/node tsx

// src/app.ts
import Fastify from 'fastify'
import { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
import swagger from '@fastify/swagger'
import swaggerUi from '@fastify/swagger-ui'
import usersRoute from './routes/users'
 
export async function buildApp() {
  const app = Fastify({
    logger: true
  }).withTypeProvider<TypeBoxTypeProvider>()
 
  await app.register(swagger, {
    openapi: {
      info: {
        title: 'Users API',
        version: '1.0.0'
      }
    }
  })
 
  await app.register(swaggerUi, {
    routePrefix: '/docs'
  })
 
  await app.register(usersRoute, { prefix: '/api/v1' })
 
  app.setErrorHandler((error, req, reply) => {
    if (error.validation) {
      return reply.code(400).send({
        statusCode: 400,
        error: 'Validation Error',
        message: error.message,
        details: error.validation
      })
    }
 
    app.log.error(error)
    return reply.code(500).send({
      statusCode: 500,
      error: 'Internal Server Error',
      message: 'Something went wrong'
    })
  })
 
  return app
}

// src/server.ts
import { buildApp } from './app'
 
async function main() {
  const app = await buildApp()
  await app.listen({ port: 3000, host: '0.0.0.0' })
}
 
main()

// src/schemas/user.ts
import { Type } from '@sinclair/typebox'
 
export const UserIdParams = Type.Object({
  id: Type.Number({ minimum: 1 })
})
 
export const CreateUserBody = Type.Object({
  name: Type.String({ minLength: 1, maxLength: 100 }),
  email: Type.String({ format: 'email' }),
  role: Type.Union([
    Type.Literal('admin'),
    Type.Literal('editor'),
    Type.Literal('viewer')
  ])
})
 
export const UserResponse = Type.Object({
  id: Type.Number(),
  name: Type.String(),
  email: Type.String(),
  role: Type.String(),
  createdAt: Type.String({ format: 'date-time' })
})
 
export const UserListQuery = Type.Object({
  page: Type.Optional(Type.Number({ minimum: 1, default: 1 })),
  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 20 }))
})

// src/routes/users.ts
import { FastifyPluginAsyncTypebox } from '@fastify/type-provider-typebox'
import { Type } from '@sinclair/typebox'
import {
  UserIdParams,
  CreateUserBody,
  UserResponse,
  UserListQuery
} from '../schemas/user'
 
// 아래는 실제 DB 레이어로 교체할 인-메모리 스텁입니다
type UserRecord = { id: number; name: string; email: string; role: string; createdAt: string }
const db: UserRecord[] = []
let nextId = 1
 
async function fetchUsers(page: number, limit: number): Promise<UserRecord[]> {
  return db.slice((page - 1) * limit, page * limit)
}
 
async function findUser(id: number): Promise<UserRecord | undefined> {
  return db.find(u => u.id === id)
}
 
async function findUserByEmail(email: string): Promise<UserRecord | undefined> {
  return db.find(u => u.email === email)
}
 
async function createUser(data: { name: string; email: string; role: string }): Promise<UserRecord> {
  const user: UserRecord = { ...data, id: nextId++, createdAt: new Date().toISOString() }
  db.push(user)
  return user
}
 
const usersRoute: FastifyPluginAsyncTypebox = async (app) => {
  // GET /users — 목록 조회
  app.get('/users', {
    schema: {
      querystring: UserListQuery,
      response: {
        200: Type.Array(UserResponse)
      }
    }
  }, async (req) => {
    // req.query.page, req.query.limit 모두 number | undefined로 추론됩니다
    const { page = 1, limit = 20 } = req.query
    return fetchUsers(page, limit)
  })
 
  // GET /users/:id — 단건 조회
  app.get('/users/:id', {
    schema: {
      params: UserIdParams,
      response: {
        200: UserResponse,
        404: Type.Object({ message: Type.String() })
      }
    }
  }, async (req, reply) => {
    // req.params.id는 number로 추론됩니다
    // Ajv가 coerceTypes 옵션으로 URL의 문자열 "42"를 숫자 42로 변환합니다
    const user = await findUser(req.params.id)
    if (!user) {
      return reply.code(404).send({ message: 'User not found' })
    }
    return user
  })
 
  // POST /users — 생성
  app.post('/users', {
    schema: {
      body: CreateUserBody,
      response: {
        201: UserResponse,
        409: Type.Object({ message: Type.String() })
      }
    },
    preHandler: async (req, reply) => {
      // 비동기 검증은 preHandler 훅에서 처리합니다
      // Ajv $async를 직접 쓰면 DoS 위험이 있습니다
      const existing = await findUserByEmail(req.body.email)
      if (existing) {
        return reply.code(409).send({ message: 'Email already exists' })
      }
    }
  }, async (req, reply) => {
    // req.body.name, req.body.email, req.body.role 모두 완전히 타입 추론됩니다
    const user = await createUser(req.body)
    return reply.code(201).send(user)
  })
}
 
export default usersRoute

// 동작하지 않습니다 — v5에서 제거된 시그니처
app.listen(3000, '0.0.0.0', () => {
  console.log('listening')
})
 
// v5에서는 객체 형태를 사용합니다
await app.listen({ port: 3000, host: '0.0.0.0' })

// withTypeProvider 없이는 body가 unknown으로 추론됩니다
const app = Fastify()
 
// 이렇게 해야 라우트 핸들러에서 타입 추론이 됩니다
const app = Fastify().withTypeProvider<TypeBoxTypeProvider>()

// 위험한 방식 — 오류 없이 검증이 조용히 무시됩니다
schema: {
  params: { id: { type: 'number' } }
}
 
// 올바른 방식 — type: 'object' + properties 구조를 갖춘 JSON Schema
schema: {
  params: Type.Object({ id: Type.Number() })
}