Route Handlers

Route Handlers

Route Handlers는 특정 라우트에 대한 커스텀 요청 핸들러를 만들게 해주는 기능이에요. 웹의 Request와 Response API를 사용해요. 앱 라우터에서 API 엔드포인트를 만들 때 가장 자연스러운 방법이죠.

출처: https://nextjs.org/docs/app/getting-started/route-handlers

참고: Route Handlers는 App Router(app 디렉토리) 안에서만 사용할 수 있어요. Pages Router의 API Routes에 해당하며, 둘을 함께 쓸 필요는 없어요.

컨벤션

Route Handlers는 app 디렉토리 안의 route.js|ts 파일에 정의해요. page.js와 layout.js처럼 app 디렉토리 어디든 중첩할 수 있지만, 같은 라우트 세그먼트 레벨에서 page.js와 route.js가 둘 다 있을 수는 없어요.

지원되는 HTTP 메서드

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS 메서드를 지원해요. 지원되지 않는 메서드가 호출되면 Next.js는 405 Method Not Allowed를 반환해요.

확장된 NextRequest / NextResponse API

네이티브 Request·Response API 외에도 Next.js는 NextRequest와 NextResponse로 고급 사례를 편리하게 다루는 헬퍼를 제공해요.

캐싱

Route Handlers는 기본적으로 캐시되지 않아요. GET 메서드에 한해 캐싱을 선택할 수 있고, 다른 HTTP 메서드는 캐시되지 않아요. GET을 캐시하려면 라우트 설정 옵션으로 export const dynamic = 'force-static'을 써요.

export const dynamic = 'force-static'

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  })
  const data = await res.json()

  return Response.json({ data })
}

캐시된 GET 옆에 같은 파일에 있더라도 다른 HTTP 메서드는 캐시되지 않아요.

Cache Components와 함께

Cache Components가 활성화되면 GET Route Handler는 일반 UI 라우트와 같은 모델을 따라요. 기본적으로 요청 시점에 실행되고, 캐시되지 않은 데이터·런타임 데이터에 접근하지 않으면 프리렌더링될 수 있어요. use cache를 써서 캐시되지 않은 데이터를 정적 응답에 포함할 수도 있어요.

프리렌더링은 GET 핸들러가 네트워크 요청·DB 쿼리·비동기 파일시스템 작업·요청 객체 속성(req.url, request.headers, request.cookies, request.body)·런타임 API(cookies(), headers(), connection())·비결정적 연산에 접근하면 중단돼요.

use cache는 Route Handler 본문 안에 직접 쓸 수 없어요. 헬퍼 함수로 추출해서 쓰면 캐시된 응답이 새 요청이 올 때 cacheLife에 따라 재검증돼요.

특수 Route Handlers

sitemap.ts, opengraph-image.tsx, icon.tsx 같은 특수 Route Handlers와 그 외 metadata 파일은, 요청 시점 API나 동적 설정 옵션을 쓰지 않는 한 기본적으로 정적으로 유지돼요.

라우트 해석

route는 가장 낮은 수준의 라우팅 프리미티브로 볼 수 있어요.

  • page처럼 레이아웃이나 클라이언트 내비게이션에 참여하지 않아요.
  • page.js와 같은 라우트에 route.js가 있으면 충돌이에요.
Page Route 결과
app/page.js app/route.js 충돌
app/page.js app/api/route.js 유효
app/[user]/page.js app/api/route.js 유효

각 route.js 또는 page.js 파일은 그 라우트의 모든 HTTP 동사를 점유해요.

TypeScript에서 라우트 컨텍스트

Route Handler의 context 파라미터는 전역 RouteContext 헬퍼로 타입을 지정할 수 있어요.

import type { NextRequest } from 'next/server'

export async function GET(_req: NextRequest, ctx: RouteContext<'/users/[id]'>) {
  const { id } = await ctx.params
  return Response.json({ id })
}

타입은 next dev, next build 또는 next typegen 중에 생성돼요.

더 알아보기