[next 14 공식문서 부시기] 2.5. Router Handlers

Route Handlers

Route Handlers 사용하면 웹 요청 및 응답 API 를 사용하여 특정 경로에 대한 사용자 정의 요청 핸들러를 생성할 수 있습니다

 

App 디렉터리 내에서만 사용할 수 있습니다.

Convention

 

Route Handlers는 App 디렉터리 내의 Route.js|ts 파일에 정의되어 있습니다.

HTTP 메서드 지원

GET, POST, PUT, PATCH, DELETE, HEAD 및 OPTIONS 와 같은 HTTP 메서드가 지원됩니다. 지원되지 않는 메서드가 호출되면 Next.js 는 405 Method Not Allowed 응답을 반환합니다.

경로 지정 관련

• 페이지와 같은 레이아웃이나 클라이언트 측 탐색에는 참여하지 않습니다.
• page.js와 동일한 경로에 route.js 파일이 있을 수 없습니다.

기능

캐싱

Route Handlers 응답 객체와 함께 GET 메서드를 사용할 때 기본적으로 캐시됩니다.

 

캐싱에서 제외

• GET 메소드와 함께 Request 객체를 사용
• 다른 HTTP 메서드를 사용
• 쿠키 및 헤더와 같은 동적 기능을 사용
• 세그먼트 구성 옵션에 dynamic 모드를 수동으로 지정

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const id = searchParams.get('id')
  const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY!,
    },
  })
  const product = await res.json()

  return Response.json({ product })
}

캐시된 데이터 재검증

 

next.revalidate 옵션을 사용하여 캐시된 데이터의 유효성을 다시 검사할 수 있습니다.

 

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    next: { revalidate: 60 }, // Revalidate every 60 seconds
  })
  const data = await res.json()

  return Response.json(data)
}

또는 revalidate segment config option을 사용할 수 있습니다.

export const revalidate = 60

동적 기능

 

Route Handlers 는 쿠키 및 헤더와 같은 Next.js 의 동적 기능과 함께 사용이 가능하다.

cookies()

 

next/headers 의 쿠키를 사용하여 쿠키를 읽거나 설정 가능하다. 이 서버 함수는 Route Handler 에서 직접 호출되거나 다른 함수 내에 중첩될 수 있습니다.

 

또는 기본적으로 Set-Cookie 헤더를 사용하여 새 응답을 반환할 수 있습니다.

import { cookies } from 'next/headers'

export async function GET(request: Request) {
  const cookieStore = cookies()
  const token = cookieStore.get('token')

  return new Response('Hello, Next.js!', {
    status: 200,
    headers: { 'Set-Cookie': `token=${token.value}` },
  })
}

기본 웹 요청(NextRequest)에서 쿠키를 읽어 올 수도 있습니다.

import { type NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const token = request.cookies.get('token')
}

headers()

쿠키와 같이 next/headers 에서 헤더가 포함된 헤더를 읽을 수 있습니다. 이 서버 함수는 Route Handler에서 직접 호출되거나 다른 함수 내에 중첩될 수 있습니다.

 

이 헤더 인스턴스는 읽기 전용입니다. 헤더를 설정하려면 새 헤더가 포함된 새 응답을 반환해야 합니다.

 

import { headers } from 'next/headers'

export async function GET(request: Request) {
  const headersList = headers()
  const referer = headersList.get('referer')

  return new Response('Hello, Next.js!', {
    status: 200,
    headers: { referer: referer },
  })
}

기본 웹 요청(NextRequest)에서 헤더를 읽어 올 수도 있습니다.

import { type NextRequest } from 'next/server'

export async function GET(request: NextRequest) {
  const requestHeaders = new Headers(request.headers)
}

리다이렉트

 

redirect()

 

import { redirect } from 'next/navigation'

export async function GET(request: Request) {
  redirect('https://nextjs.org/')
}

동적 경로 세그먼트

 

Route Handlers 는Dynamic Segments의 동적 데이터를 활용해 요청 핸들러를 생성할 수 있습니다.

export async function GET(
  request: Request,
  { params }: { params: { slug: string } }
) {
  const slug = params.slug // 'a', 'b', or 'c'
}

URL Query Parameters

 

Route Handler에 전달된 Request 객체는 쿼리 매개변수를 더 쉽게 처리하는 것을 포함하여 몇 가지 추가 편의 메서드가 추가된 NextRequest 인스턴스입니다.

 

import { type NextRequest } from 'next/server'

export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const query = searchParams.get('query')
  // query is "hello" for /api/search?query=hello
}

Streaming

 

Streaming은 AI 생성 콘텐츠를 위해 OpenAI와 같은 LLM(대형 언어 모델)과 함께 일반적으로 사용됩니다. AI SDK DOCS

Webhooks

 

Route Handler를 사용하여 타사 서비스로부터 webhooks 를 수신할 수 있습니다.

export async function POST(request: Request) {
  try {
    const text = await request.text()
    // Process the webhook payload
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    })
  }

  return new Response('Success!', {
    status: 200,
  })
}

CORS 설정

 

표준 웹 API 메소드를 사용하여 응답에 CORS 헤더를 설정할 수 있습니다

export const dynamic = 'force-dynamic' // defaults to auto

export async function GET(request: Request) {
  return new Response('Hello, Next.js!', {
    status: 200,
    headers: {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type, Authorization',
    },
  })
}

세그먼트 구성 옵션

 

경로 세그먼트 옵션을 사용하면 관련 변수를 직접 내보내 페이지, 레이아웃 또는 Route Handler의 동작을 구성할 수 있습니다.

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'

export  default  function  MyComponent() {}

---

참고

https://nextjs.org/docs