라우트 핸들러

라우트 핸들러를 사용하면 웹 Request와 Response API를 사용하여 주어진 라우트에 대한 사용자 정의 요청 핸들러를 생성할 수 있습니다.

알아두면 좋은 점: 라우트 핸들러는 app 디렉토리 내에서만 사용할 수 있습니다. 이들은 pages 디렉토리 내의 API 라우트와 동등하므로 API 라우트와 라우트 핸들러를 함께 사용할 필요가 없습니다.

규칙

라우트 핸들러는 app 디렉토리 내의 route.js|ts 파일에 정의됩니다:

app/api/route.ts

export async function GET(request: Request) {}

app/api/route.js

export async function GET(request) {}

라우트 핸들러는 page.js와 layout.js와 유사하게 app 디렉토리 내 어디에서나 중첩될 수 있습니다. 그러나 page.js와 동일한 라우트 세그먼트 레벨에 route.js 파일이 있을 수 없습니다.

지원되는 HTTP 메서드

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

확장된 `NextRequest`와 `NextResponse` API

네이티브 Request와 Response API를 지원하는 것 외에도, Next.js는 고급 사용 사례를 위한 편리한 헬퍼를 제공하기 위해 NextRequest와 NextResponse로 이들을 확장합니다.

동작

캐싱

라우트 핸들러는 기본적으로 캐시되지 않습니다. 그러나 GET 메서드에 대해 캐싱을 선택할 수 있습니다. 이를 위해 라우트 핸들러 파일에서 export const dynamic = 'force-static'과 같은 라우트 구성 옵션을 사용하세요.

app/items/route.ts

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 });
}

app/items/route.js

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 });
}

특수 라우트 핸들러

sitemap.ts, opengraph-image.tsx, icon.tsx와 같은 특수 라우트 핸들러와 기타 메타데이터 파일은 동적 함수나 동적 구성 옵션을 사용하지 않는 한 기본적으로 정적으로 유지됩니다.

라우팅 처리

route를 가장 기본적인 라우팅 요소로 간주됩니다.

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

페이지	라우트	결과
`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 메서드를 처리합니다.

app/page.js

export default function Page() {
  return <h1>Hello, Next.js!</h1>;
}
 
// ❌ 충돌
// `app/route.js`
export async function POST(request) {}

예시

다음 예시는 라우트 핸들러를 다른 Next.js API 및 기능과 결합하는 방법을 보여줍니다.

캐시된 데이터 재검증

next.revalidate 옵션을 사용하여 캐시된 데이터를 재검증할 수 있습니다:

app/items/route.ts

export async function GET() {
  const res = await fetch("https://data.mongodb-api.com/...", {
    next: { revalidate: 60 }, // 60초마다 재검증
  });
  const data = await res.json();
 
  return Response.json(data);
}

app/items/route.js

export async function GET() {
  const res = await fetch("https://data.mongodb-api.com/...", {
    next: { revalidate: 60 }, // 60초마다 재검증
  });
  const data = await res.json();
 
  return Response.json(data);
}

또는 revalidate 세그먼트 구성 옵션을 사용할 수 있습니다:

export const revalidate = 60;

동적 함수

라우트 핸들러는 Next.js의 cookies와 headers와 같은 동적 함수와 함께 사용할 수 있습니다.

쿠키

next/headers의 cookies를 사용하여 쿠키를 읽거나 설정할 수 있습니다. 이 서버 함수는 라우트 핸들러에서 직접 호출하거나 다른 함수 내에 중첩할 수 있습니다.

또는 Set-Cookie 헤더를 사용하여 새 Response를 반환할 수 있습니다.

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}` },
  });
}

app/api/route.js

import { cookies } from "next/headers";
 
export async function GET(request) {
  const cookieStore = cookies();
  const token = cookieStore.get("token");
 
  return new Response("Hello, Next.js!", {
    status: 200,
    headers: { "Set-Cookie": `token=${token}` },
  });
}

또한 요청(NextRequest)에서 쿠키를 읽기 위해 기본 Web API를 사용할 수 있습니다:

app/api/route.ts

import { type NextRequest } from "next/server";
 
export async function GET(request: NextRequest) {
  const token = request.cookies.get("token");
}

app/api/route.js

export async function GET(request) {
  const token = request.cookies.get("token");
}

헤더

next/headers의 headers를 사용하여 헤더를 읽을 수 있습니다. 이 서버 함수는 라우트 핸들러에서 직접 호출하거나 다른 함수 내에 중첩할 수 있습니다.

이 headers 인스턴스는 읽기 전용입니다. 헤더를 설정하려면 새로운 headers로 새 Response를 반환해야 합니다.

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.js

import { headers } from "next/headers";
 
export async function GET(request) {
  const headersList = headers();
  const referer = headersList.get("referer");
 
  return new Response("Hello, Next.js!", {
    status: 200,
    headers: { referer: referer },
  });
}

또한 요청(NextRequest)에서 헤더를 읽기 위해 기본 Web API를 사용할 수 있습니다:

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.js

export async function GET(request) {
  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/");
}

app/api/route.js

import { redirect } from "next/navigation";
 
export async function GET(request) {
  redirect("https://nextjs.org/");
}

동적 라우트 세그먼트

계속하기 전에 라우트 정의하기 페이지를 읽는 것을 추천합니다.

라우트 핸들러는 동적 세그먼트를 사용하여 동적 데이터로부터 요청 핸들러를 생성할 수 있습니다.

app/items/[slug]/route.ts

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

app/items/[slug]/route.js

export async function GET(request, { params }) {
  const slug = params.slug; // 'a', 'b', 또는 'c'
}

라우트	예시 URL	`params`
`app/items/[slug]/route.js`	`/items/a`	`{ slug: 'a' }`
`app/items/[slug]/route.js`	`/items/b`	`{ slug: 'b' }`
`app/items/[slug]/route.js`	`/items/c`	`{ slug: 'c' }`

URL 쿼리 매개변수

라우트 핸들러에 전달된 요청 객체는 일부 추가 편의 메서드를 포함하는 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는 /api/search?query=hello에 대해 "hello"입니다
}

app/api/search/route.js

export function GET(request) {
  const searchParams = request.nextUrl.searchParams;
  const query = searchParams.get("query");
  // query는 /api/search?query=hello에 대해 "hello"입니다
}

스트리밍

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

app/api/chat/route.ts

import { openai } from "@ai-sdk/openai";
import { StreamingTextResponse, streamText } from "ai";
 
export async function POST(req) {
  const { messages } = await req.json();
  const result = await streamText({
    model: openai("gpt-4-turbo"),
    messages,
  });
 
  return new StreamingTextResponse(result.toAIStream());
}

app/api/chat/route.js

import { openai } from "@ai-sdk/openai";
import { StreamingTextResponse, streamText } from "ai";
 
export async function POST(req: Request) {
  const { messages } = await req.json();
  const result = await streamText({
    model: openai("gpt-4-turbo"),
    messages,
  });
 
  return new StreamingTextResponse(result.toAIStream());
}

이러한 추상화는 스트림을 생성하기 위해 Web API를 사용합니다. 기본 Web 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);
}

app/api/route.js

// https://developer.mozilla.org/docs/Web/API/ReadableStream#convert_async_iterator_to_stream
function iteratorToStream(iterator) {
  return new ReadableStream({
    async pull(controller) {
      const { value, done } = await iterator.next();
 
      if (done) {
        controller.close();
      } else {
        controller.enqueue(value);
      }
    },
  });
}
 
function sleep(time) {
  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);
}

요청 본문

표준 Web API 메서드를 사용하여 Request 본문을 읽을 수 있습니다:

app/items/route.ts

export async function POST(request: Request) {
  const res = await request.json();
  return Response.json({ res });
}

app/items/route.js

export async function POST(request) {
  const res = await request.json();
  return Response.json({ res });
}

요청 본문 FormData

request.formData() 함수를 사용하여 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 });
}

app/items/route.js

export async function POST(request) {
  const formData = await request.formData();
  const name = formData.get("name");
  const email = formData.get("email");
  return Response.json({ name, email });
}

formData 데이터는 모두 문자열이므로, 요청을 검증하고 선호하는 형식(예: number)으로 데이터를 검색하려면 zod-form-data를 사용하고 싶을 수 있습니다.

CORS

표준 Web API 메서드를 사용하여 특정 라우트 핸들러에 대한 CORS 헤더를 설정할 수 있습니다:

app/api/route.ts

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",
    },
  });
}

app/api/route.js

export async function GET(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",
    },
  });
}

알아두면 좋은 점:

여러 라우트 핸들러에 CORS 헤더를 추가하려면 미들웨어 또는 next.config.js 파일을 사용할 수 있습니다.

또는 우리의 CORS 예제 패키지를 참조하세요.

웹훅

라우트 핸들러를 사용하여 서드파티 서비스로부터 웹훅을 수신할 수 있습니다:

app/api/route.ts

export async function POST(request: Request) {
  try {
    const text = await request.text();
    // 웹훅 페이로드 처리
  } catch (error) {
    return new Response(`웹훅 오류: ${error.message}`, {
      status: 400,
    });
  }
 
  return new Response("성공!", {
    status: 200,
  });
}

app/api/route.js

export async function POST(request) {
  try {
    const text = await request.text();
    // 웹훅 페이로드 처리
  } catch (error) {
    return new Response(`웹훅 오류: ${error.message}`, {
      status: 400,
    });
  }
 
  return new Response("성공!", {
    status: 200,
  });
}

주목할 점은, Pages 라우터의 API 라우트와 달리 bodyParser를 사용하거나 추가 구성을 할 필요가 없다는 것입니다.

UI가 아닌 응답

라우트 핸들러를 사용하여 UI가 아닌 콘텐츠를 반환할 수 있습니다. sitemap.xml, robots.txt, 앱 아이콘, 그리고 오픈 그래프 이미지는 모두 기본적으로 지원됩니다.

app/rss.xml/route.ts

export async function GET() {
  return new Response(
    `<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
 
<channel>
  <title>Next.js 문서</title>
  <link>https://nextjs.org/docs</link>
  <description>웹을 위한 React 프레임워크</description>
</channel>
 
</rss>`,
    {
      headers: {
        "Content-Type": "text/xml",
      },
    }
  );
}

app/rss.xml/route.js

export async function GET() {
  return new Response(`<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
 
<channel>
  <title>Next.js 문서</title>
  <link>https://nextjs.org/docs</link>
  <description>웹을 위한 React 프레임워크</description>
</channel>
 
</rss>`);
}

세그먼트 구성 옵션

라우트 핸들러는 페이지 및 레이아웃과 동일한 라우트 세그먼트 구성을 사용합니다.

app/items/route.ts

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

app/items/route.js

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

자세한 내용은 API 참조를 참조하세요.

라우트 가로채기 미들웨어

라우트 핸들러

규칙

지원되는 HTTP 메서드

확장된 NextRequest와 NextResponse API

동작

캐싱

특수 라우트 핸들러

라우팅 처리

예시

캐시된 데이터 재검증

동적 함수

쿠키

헤더

리다이렉트

동적 라우트 세그먼트

URL 쿼리 매개변수

스트리밍

요청 본문

요청 본문 FormData

CORS

웹훅

UI가 아닌 응답

세그먼트 구성 옵션

확장된 `NextRequest`와 `NextResponse` API