2026년 현재, Nuxt.js는 풀스택 Vue 개발의 사실상 표준으로 확고히 자리잡았습니다. Nuxt의 핵심 서버 엔진인 Nitro는 Server Routes를 통해 프론트엔드와 백엔드를 단일 코드베이스에서 개발할 수 있게 해줍니다. Nuxt 4의 정식 출시와 Nitro 3의 안정화로 TypeScript 우선 API 개발, 엣지 컴퓨팅 지원, 제로 설정 배포가 가능해졌습니다. 이 글에서는 Nuxt Server Routes의 기초부터 실전 API 엔드포인트 구축까지, 2026년 기술 면접에서 요구되는 지식을 체계적으로 설명합니다.

Nitro와 Server Routes의 역할

Nitro는 Nuxt의 서버 엔진이며, Server Routes는 그 위에서 동작하는 API 엔드포인트 정의 체계입니다. 기존의 Express.js나 Fastify를 별도로 설정할 필요 없이 server/api/ 디렉토리에 파일을 배치하는 것만으로 API 라우트가 자동 생성됩니다. Nitro 3은 Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge Functions 등 모든 런타임에서 동일한 코드가 실행됩니다.

Server Routes 기초: 파일 기반 라우팅

Nuxt Server Routes는 server/api/ 디렉토리의 구조가 그대로 API 엔드포인트 경로에 매핑되는 파일 기반 라우팅을 채택하고 있습니다. 이 설계 덕분에 라우팅 설정을 별도로 작성할 필요가 없고, 디렉토리 구조만 보면 전체 API 설계를 파악할 수 있습니다.

server/api/users/index.get.tstypescript

export default defineEventHandler(async (event) => {
  const users = await prisma.user.findMany({
    select: {
      id: true,
      name: true,
      email: true,
      createdAt: true
    }
  })
  return users
})

파일명의 .get.ts 접미사는 HTTP 메서드를 지정합니다. 마찬가지로 .post.ts, .put.ts, .delete.ts, .patch.ts를 사용하여 RESTful API를 직관적으로 구축할 수 있습니다.

server/api/users/index.post.tstypescript

import { z } from 'zod'

const createUserSchema = z.object({
  name: z.string().min(2).max(100),
  email: z.string().email(),
  password: z.string().min(8)
})

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const validated = createUserSchema.parse(body)

  const hashedPassword = await hashPassword(validated.password)
  
  const user = await prisma.user.create({
    data: {
      name: validated.name,
      email: validated.email,
      password: hashedPassword
    }
  })

  return {
    id: user.id,
    name: user.name,
    email: user.email
  }
})

동적 파라미터는 대괄호를 사용하여 파일명에 포함합니다. [id].get.ts는 /api/users/123 같은 경로와 매칭되며, event.context.params.id로 파라미터를 가져올 수 있습니다.

server/api/users/[id].get.tstypescript

export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  
  const user = await prisma.user.findUnique({
    where: { id: parseInt(id!) },
    include: {
      posts: {
        orderBy: { createdAt: 'desc' },
        take: 10
      }
    }
  })

  if (!user) {
    throw createError({
      statusCode: 404,
      statusMessage: 'User not found'
    })
  }

  return user
})

미들웨어와 인증 구현

Server Routes에서는 server/middleware/ 디렉토리에 배치한 파일이 모든 요청에 대해 실행됩니다. 인증, 로깅, 레이트 리미팅 같은 횡단 관심사를 중앙에서 관리할 수 있습니다.

server/middleware/auth.tstypescript

export default defineEventHandler(async (event) => {
  const publicPaths = ['/api/auth/login', '/api/auth/register', '/api/health']
  const path = getRequestURL(event).pathname

  if (publicPaths.some(p => path.startsWith(p))) {
    return
  }

  const token = getHeader(event, 'authorization')?.replace('Bearer ', '')

  if (!token) {
    throw createError({
      statusCode: 401,
      statusMessage: 'Authentication required'
    })
  }

  try {
    const payload = await verifyJWT(token)
    event.context.user = payload
  } catch {
    throw createError({
      statusCode: 401,
      statusMessage: 'Invalid token'
    })
  }
})

특정 라우트에만 적용하는 미들웨어는 라우트 핸들러 내에서 직접 실행하는 패턴이 권장됩니다. Nitro 3에서는 미들웨어 체인을 구성하는 createMiddleware 유틸리티도 제공됩니다.

server/utils/middleware.tstypescript

import { H3Event } from 'h3'

export const requireAdmin = async (event: H3Event) => {
  const user = event.context.user
  
  if (!user || user.role !== 'admin') {
    throw createError({
      statusCode: 403,
      statusMessage: 'Admin access required'
    })
  }
}

// server/api/admin/users.get.ts
export default defineEventHandler(async (event) => {
  await requireAdmin(event)
  
  return await prisma.user.findMany({
    include: { _count: { select: { posts: true } } }
  })
})

Vue.js / Nuxt.js 면접 준비가 되셨나요?

인터랙티브 시뮬레이터, flashcards, 기술 테스트로 연습하세요.

Vue.js / Nuxt.js 탐색하기

데이터베이스 통합과 ORM 연동

Nuxt Server Routes는 Prisma, Drizzle, Kysely 같은 주요 ORM과 원활하게 통합됩니다. Nitro의 핫 리로드 기능 덕분에 개발 중 데이터베이스 스키마 변경도 즉시 반영됩니다.

server/utils/db.tstypescript

import { PrismaClient } from '@prisma/client'

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined
}

export const prisma = globalForPrisma.prisma ?? new PrismaClient({
  log: process.env.NODE_ENV === 'development' 
    ? ['query', 'error', 'warn'] 
    : ['error']
})

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma
}

트랜잭션 처리도 직관적으로 작성할 수 있습니다. 여러 데이터베이스 작업을 원자적으로 실행해야 할 때 Prisma의 $transaction 메서드를 활용합니다.

server/api/orders/index.post.tstypescript

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const userId = event.context.user.id

  const order = await prisma.$transaction(async (tx) => {
    // Create order
    const newOrder = await tx.order.create({
      data: {
        userId,
        status: 'pending',
        totalAmount: body.totalAmount
      }
    })

    // Create order items
    await tx.orderItem.createMany({
      data: body.items.map((item: any) => ({
        orderId: newOrder.id,
        productId: item.productId,
        quantity: item.quantity,
        price: item.price
      }))
    })

    // Update inventory
    for (const item of body.items) {
      await tx.product.update({
        where: { id: item.productId },
        data: {
          stock: { decrement: item.quantity }
        }
      })
    }

    return newOrder
  })

  return order
})

오류 처리와 유효성 검사

프로덕션 수준의 API에서는 적절한 오류 처리와 유효성 검사가 필수적입니다. Zod와 조합하면 타입 안전한 유효성 검사를 구현할 수 있습니다.

server/utils/validation.tstypescript

import { z, ZodError } from 'zod'
import { H3Event } from 'h3'

export async function validateBody<T extends z.ZodTypeAny>(
  event: H3Event,
  schema: T
): Promise<z.infer<T>> {
  const body = await readBody(event)
  
  try {
    return schema.parse(body)
  } catch (error) {
    if (error instanceof ZodError) {
      throw createError({
        statusCode: 400,
        statusMessage: 'Validation failed',
        data: {
          errors: error.errors.map(e => ({
            path: e.path.join('.'),
            message: e.message
          }))
        }
      })
    }
    throw error
  }
}

// server/api/products/index.post.ts
const productSchema = z.object({
  name: z.string().min(1).max(200),
  description: z.string().optional(),
  price: z.number().positive(),
  categoryId: z.number().int().positive()
})

export default defineEventHandler(async (event) => {
  const data = await validateBody(event, productSchema)
  
  return await prisma.product.create({ data })
})

캐싱과 성능 최적화

Nitro는 내장 캐싱 기능을 제공하여 API 응답을 효율적으로 캐시할 수 있습니다. 특히 읽기 빈도가 높은 엔드포인트에서는 캐싱으로 응답 시간을 크게 단축할 수 있습니다.

server/api/products/featured.get.tstypescript

export default defineCachedEventHandler(async () => {
  const products = await prisma.product.findMany({
    where: { featured: true },
    include: {
      category: true,
      _count: { select: { reviews: true } }
    },
    orderBy: { createdAt: 'desc' },
    take: 12
  })

  return products
}, {
  maxAge: 60 * 5, // 5 minutes
  staleMaxAge: 60 * 60, // 1 hour stale-while-revalidate
  swr: true
})

캐시 무효화는 관련 데이터가 업데이트될 때 프로그래밍 방식으로 실행할 수 있습니다.

server/api/products/[id].put.tstypescript

export default defineEventHandler(async (event) => {
  const id = getRouterParam(event, 'id')
  const body = await readBody(event)

  const product = await prisma.product.update({
    where: { id: parseInt(id!) },
    data: body
  })

  // Invalidate related caches
  await useStorage('cache').removeItem('nitro:handlers:products:featured')

  return product
})

WebSocket과 실시간 통신

Nitro 3에서는 WebSocket 지원이 대폭 강화되었습니다. server/routes/ 디렉토리에 WebSocket 핸들러를 배치하여 실시간 통신을 구현할 수 있습니다.

server/routes/_ws.tstypescript

export default defineWebSocketHandler({
  open(peer) {
    console.log('Client connected:', peer.id)
    peer.subscribe('notifications')
  },

  message(peer, message) {
    const data = JSON.parse(message.text())
    
    if (data.type === 'subscribe') {
      peer.subscribe(data.channel)
    } else if (data.type === 'broadcast') {
      peer.publish(data.channel, JSON.stringify(data.payload))
    }
  },

  close(peer) {
    console.log('Client disconnected:', peer.id)
  }
})

Vue.js / Nuxt.js 면접 준비가 되셨나요?

인터랙티브 시뮬레이터, flashcards, 기술 테스트로 연습하세요.

Vue.js / Nuxt.js 탐색하기

멀티테넌트 아키텍처

기업용 애플리케이션에서는 멀티테넌트 지원이 자주 요구됩니다. Server Routes에서는 미들웨어와 컨텍스트를 활용하여 테넌트 분리를 구현할 수 있습니다.

server/middleware/tenant.tstypescript

export default defineEventHandler(async (event) => {
  const host = getRequestHost(event)
  const subdomain = host.split('.')[0]

  if (subdomain && subdomain !== 'www') {
    const tenant = await prisma.tenant.findUnique({
      where: { subdomain }
    })

    if (!tenant) {
      throw createError({
        statusCode: 404,
        statusMessage: 'Tenant not found'
      })
    }

    event.context.tenant = tenant
  }
})

// server/api/projects/index.get.ts
export default defineEventHandler(async (event) => {
  const tenantId = event.context.tenant?.id

  return await prisma.project.findMany({
    where: { tenantId },
    orderBy: { createdAt: 'desc' }
  })
})

배포 전략

Nitro의 가장 큰 강점은 동일한 코드를 모든 플랫폼에 배포할 수 있다는 점입니다. nuxt.config.ts에서 nitro.preset을 지정하는 것만으로 각 플랫폼에 최적화된 빌드가 생성됩니다.

nuxt.config.tstypescript

export default defineNuxtConfig({
  nitro: {
    preset: 'cloudflare-pages', // or 'vercel', 'netlify', 'node-server'
    
    // Storage configuration
    storage: {
      cache: {
        driver: 'cloudflare-kv-binding',
        binding: 'CACHE'
      }
    },

    // Prerender static pages
    prerender: {
      routes: ['/about', '/pricing', '/docs'],
      crawlLinks: true
    }
  }
})

Node.js 서버로 배포할 경우, PM2나 Docker와 결합하여 프로덕션 환경을 구성할 수 있습니다.

dockerfile

# Dockerfile
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:22-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.output ./
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node", "server/index.mjs"]

테스트 전략

Server Routes 테스트는 Vitest를 사용하여 단위 테스트와 통합 테스트를 작성할 수 있습니다. Nitro의 $fetch 유틸리티를 활용하면 실제 HTTP 요청을 시뮬레이션할 수 있습니다.

tests/api/users.test.tstypescript

import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import { setup, $fetch } from '@nuxt/test-utils'

describe('Users API', async () => {
  await setup({ server: true })

  it('returns user list', async () => {
    const users = await $fetch('/api/users')
    expect(Array.isArray(users)).toBe(true)
  })

  it('creates a new user', async () => {
    const user = await $fetch('/api/users', {
      method: 'POST',
      body: {
        name: 'Test User',
        email: 'test@example.com',
        password: 'securepassword123'
      }
    })

    expect(user).toHaveProperty('id')
    expect(user.name).toBe('Test User')
  })

  it('returns 400 for invalid input', async () => {
    await expect(
      $fetch('/api/users', {
        method: 'POST',
        body: { name: '' }
      })
    ).rejects.toThrow()
  })
})

결론

Nuxt Server Routes와 Nitro의 조합은 2026년 풀스택 Vue 개발에서 가장 효율적인 접근 방식입니다. 파일 기반 라우팅을 통한 직관적인 API 설계, TypeScript를 통한 타입 안전성, 그리고 엣지 컴퓨팅 지원 배포 유연성 덕분에 개발자는 비즈니스 로직에 집중할 수 있습니다. 이 글에서 설명한 인증 패턴, 데이터베이스 통합, 캐싱 전략, 테스트 기법을 결합하면 확장 가능하고 유지보수가 용이한 애플리케이션을 구축할 수 있습니다. 기술 면접에서는 이러한 개념을 실제 코드 예제와 함께 설명할 수 있는 능력이 요구됩니다.

연습을 시작하세요!

면접 시뮬레이터와 기술 테스트로 지식을 테스트하세요.

무료 계정 만들기

2026년 Nuxt Nitro와 Server Routes 완벽 가이드: 풀스택 Vue 개발과 API 엔드포인트 구축

Server Routes 기초: 파일 기반 라우팅

미들웨어와 인증 구현

Vue.js / Nuxt.js 면접 준비가 되셨나요?

데이터베이스 통합과 ORM 연동

오류 처리와 유효성 검사

캐싱과 성능 최적화

WebSocket과 실시간 통신

Vue.js / Nuxt.js 면접 준비가 되셨나요?

멀티테넌트 아키텍처

배포 전략

테스트 전략

결론

연습을 시작하세요!

관련 기사

2026년 Vue 3와 TypeScript: 타입 안전한 Props, Emits, 컴포저블

2026년 Vue 3 테스팅: Vitest, Vue Test Utils 그리고 면접 질문

2026년 Vue 3 성능의 모든 것: Vapor Mode, Alien Signals 그리고 면접 질문