NextJs 13 이후 - Route Handlers

Route handler 를 사용하면 특정 요청에 대한 커스텀 요청 핸들러를 생성할 수 있다.

convention

Route handler 는 app/api 폴더 내에 route.ts 파일에 정의된다.

// app/api/route.ts
export const dynamic = 'force-dynamic' // defaults to force-static
export async function GET(request: Request) {}

HTTP methods 지원

HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) 를 지원하고 지원되지않는 메서드로 요청이 왔을때 NextJs는 405 Method Not Allowed 를 응답한다.

NextRequest, NextResponse 지원

기본 요청 응답 외에도 NextJs는 고급 사용 사례를 위한 편리한 도움을 주기위해 확장된 NextRequest, NextResponse를 지원한다.

Behavior

Caching

Route handler는 기본적으로 GET 메서드를 사용할때 응답 객체를 캐싱을 한다.

// app/items/route.ts
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 })
}

Response.json() 방식은 Typescript 5.2 이상부터 사용가능하다. 이전버전은 NextResponse.json()을 사용해야한다.

Caching 해제 방법

GET 메서드를 사용할때 Request를 사용한다.
다른 HTTP 메서드를 사용한다.
cookies, headers와 같은 동적 기능을 사용한다.
segment config options 값을 지정한다.

Ex)

// app/products/api/route.ts
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 })
}

// app/items/route.ts
export async function POST() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
    body: JSON.stringify({ time: new Date().toISOString() }),
  })

  const data = await res.json()

  return Response.json(data)
}

Route 결정

page와 route는 같은 폴더내에 존재할 수 없다.

// app/page.js
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}

// ❌ Conflict
// `app/route.js`
export async function POST(request) {}

사용 예시

재검증 캐시 데이터

next.revalidate 옵션을 사용하여 캐시를 재검증하는 옵션을 지정할 수있다.

// app/items/route.ts
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 handler는 cookies와 header와 같은 동적기능을 사용할수 있다.

Cookies

이 서버 함수는 Route handler에서 직접 호출되거나 다른 함수 내에 중첩될 수 있다.

이 쿠키는 읽기 전용이다. 응답헤더에 쿠키를 내려주려면 아래와 같이 쿠키를 반환해야한다.

// app/api/route.ts
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를 사용하여 쿠키를 읽을 수 있다.

// app/api/route.ts
import { type NextRequest } from 'next/server'

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

헤더도 마찬가지로 이 서버 함수는 Route handler에서 직접 호출되거나 다른 함수 내에 중첩될 수 있다.

이 headers인스턴스는 읽기 전용이다. Response헤더를 설정하려면 new 를 사용 하여 new headers 를 반환해야 한다 .

// app/api/route.ts
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 },
  })
}

// app/api/route.ts
import { type NextRequest } from 'next/server'

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

리다이렉트

// app/api/route.ts
import { redirect } from 'next/navigation'

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

동적 Route Segment

Route handler는 동적 Segment를 사용하여 동적 데이터에서 요청 핸들러를 생성할 수 있다.

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

URL Query Parameter

Route handler에 전달된 요청 객체는 쿼리 파라미터를 더 쉽게 처리하는 메서드가 NextRequest 인스턴스안에 있다.

// app/api/search/route.ts
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
}

스트리밍

스트리밍은 AI 생성 콘텐츠를 위해 OpenAI와 같은 LLM(대형 언어 모델)과 함께 일반적으로 사용된다. AI SDK 에 대해 자세히 알아보기.

// app/api/chat/route.ts
import OpenAI from 'openai'
import { OpenAIStream, StreamingTextResponse } from 'ai'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

export const runtime = 'edge'

export async function POST(req: Request) {
  const { messages } = await req.json()
  const response = await openai.chat.completions.create({
    model: 'gpt-3.5-turbo',
    stream: true,
    messages,
  })

  const stream = OpenAIStream(response)

  return new StreamingTextResponse(stream)
}

이러한 추상화는 웹 API를 사용하여 스트림을 생성한다. 기본 웹 API를 직접 사용할 수도 있다.

// app/api/route.ts
// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator: any) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next()

      if (done) {
        controller.close()
      } else {
        controller.enqueue(value)
      }
    },
  })
}

function sleep(time: number) {
  return new Promise((resolve) => {
    setTimeout(resolve, time)
  })
}

const encoder = new TextEncoder()

async function* makeIterator() {
  yield encoder.encode('<p>One</p>')
  await sleep(200)
  yield encoder.encode('<p>Two</p>')
  await sleep(200)
  yield encoder.encode('<p>Three</p>')
}

export async function GET() {
  const iterator = makeIterator()
  const stream = iteratorToStream(iterator)

  return new Response(stream)
}

Request Body

일반적인 요청 바디를 읽는 방법

// app/items/route.ts
export async function POST(request: Request) {
  const res = await request.json()
  return Response.json({ res })
}

Request Body FormData

Form data를 읽는 방법으로 request.formData() 를 사용할 수 있다.

// app/items/route.ts
export async function POST(request: Request) {
  const formData = await request.formData()
  const name = formData.get('name')
  const email = formData.get('email')
  return Response.json({ name, email })
}

formdata의 타입은 string 이고 zod-form-data라이브러리를 통해 요청값을 검증할 수 있고 타입을 변경할 수 있다.

CORS

CORS 응답헤더를 설정하는 방법이다.

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

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',
    },
  })
}

Non-UI Response

Route handler를 통해 UI 콘텐츠를 보여주지 않으려면 (sitemap.xml, robots.tsx, app icons 등의 경우)

// app/res.xml/route.ts
export const dynamic = 'force-dynamic' // defaults to force-static

export async function GET() {
  return new Response(`<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
 
<channel>
  <title>Next.js Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</description>
</channel>
 
</rss>`)
}

Segment Config Options

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

참고

NextJs 공식문서