[Routing] NEXT.js beta 한글 번역 : Routing - Route Handlers / 라우트 핸들러

Routing - Route Handlers / 라우트 핸들러

라우트 핸들러를 사용하면 웹 요청 및 응답 API를 사용하여 지정된 경로에 대한 사용자 지정 요청 핸들러를 만들 수 있습니다.

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

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

// app/api/route.ts
export async function GET(request: 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

기본 요청 및 응답을 지원할 뿐만 아니라. Next.js는 고급 사용 사례를 위한 편리한 도우미를 제공하기 위해 NextRequest 및 NextResponse로 이를 확장합니다.

 

동작 : 정적 라우트 핸들러

라우트 핸들러는 기본적으로 Response 객체와 함께 GET 메서드를 사용할 때 정적으로 평가됩니다.

// app/items/route.ts

import { NextResponse } from 'next/server';

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 NextResponse.json({ data })
}

TypeScript 경고: Response.json()이 유효하지만 네이티브 TypeScript 유형은 현재 오류를 표시하고, 대신 입력된 응답에 NextResponse.json()을 사용할 수 있습니다.

정적 가져오기는 robots.txt, rss.xml, sitemap.xml 및 기타 경로에 대한 사용자 지정 경로 핸들러를 생성하는 데 유용할 수 있습니다. 예시를 참조하세요.

 

동적 라우트 핸들러

라우트 핸들러는 다음과 같은 경우에 동적으로 평가됩니다:

• GET 메서드와 함께 Request 객체를 사용하는 경우.
• 다른 HTTP 메서드를 사용하는 경우.
• cookies 및 headers와 같은 다이나믹 함수를 사용하는 경우.

예를 들어:

// app/products/api/route.ts

import { NextResponse } from 'next/server';

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 NextResponse.json({ product })
}

마찬가지로 POST 메서드를 사용하면 라우트 핸들러가 동적으로 평가됩니다.

// app/items/route.ts

import { NextResponse } from 'next/server';

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 NextResponse.json(data);
}

참고: 이전에는 form 제출 처리와 같은 사용 사례에 API 라우트를 사용할 수 있었습니다. 라우트 핸들러는 이러한 사용 사례에 적합한 솔루션이 아닐 수 있습니다. 준비가 되면 이를 위한 변형을 사용할 것을 권장할 예정입니다.

 

Route 해상도

route를 가장 낮은 수준의 라우팅 프리미티브로 간주할 수 있습니다.

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

각 route.js 또는 page.js 파일은 해당 경로에 대한 모든 HTTP 동사를 대신합니다.

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

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

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

 

정적 데이터 재검증

next.revalidate 옵션을 사용하여 정적 데이터 가져오기의 유효성을 재검증할 수 있습니다:

// app/items/route.ts

import { NextResponse } from 'next/server';

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 NextResponse.json(data)
}

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

export const revalidate = 60;

 

동적 함수

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

쿠키
next/headers의 cookies로 쿠키를 읽을 수 있습니다. 이 서버 함수는 라우트 핸들러에서 직접 호출하거나 다른 함수 내부에 중첩할 수 있습니다. 이 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}` }
  });
}

또는 기본 웹 API 위에 추상화를 사용하여 쿠키를 읽을 수 있습니다(NextRequest):

// app/api/route.ts

import { type NextRequest } from 'next/server'

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

 

헤더

next/header에서 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 }
  });
}

또는 기본 웹 API 위에 추상화를 사용하여 헤더를 읽을 수 있습니다(NextRequest):

// 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 세그먼트

계속하기 전에 defining routes 페이지를 읽어보시기 바랍니다.
라우트 핸들러는 동적 세그먼트를 사용하여 동적 데이터에서 요청 핸들러를 만들 수 있습니다.

// app/items/[slug]/route.js

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

참고: generateStaticParams() 사용은 아직 라우트 핸들러와 함께 지원되지 않습니다.

 

스트리밍

// https://developer.mozilla.org/en-US/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

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

// app/items/route.ts

import { NextResponse } from 'next/server';

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

 

CORS

표준 웹 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',
    }
  });
}

 

Edge 및 Node.js 런타임

라우트 핸들러에는 스트리밍 지원을 포함해 Edge와 Node.js 런타임을 모두 원활하게 지원하는 동형 웹 API가 있습니다. 라우트 핸들러는 페이지 및 레이아웃과 동일한 라우트 세그먼트 구성을 사용하기 때문에 범용 정적으로 재생성되는 라우트 핸들러와 같이 오랫동안 기다려온 기능을 지원합니다.

runtime 세그먼트 구성 옵션을 사용하여 런타임을 지정할 수 있습니다:

export const runtime = 'edge'; // 'nodejs' is the default

 

UI 가 아닌 응답

라우트 핸들러를 사용하여 UI가 아닌 콘텐츠를 반환할 수 있습니다. sitemap.xml, robots.txt, favicon.ico, 오픈 그래프 이미지에는 모두 SEO 지원이 내장되어 있다는 점에 유의하세요.

// 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 Documentation</title>
  <link>https://nextjs.org/docs</link>
  <description>The React Framework for the Web</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'

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