Обработчики маршрутов (Route Handlers)

Обработчики маршрутов (Route Handlers) позволяют создавать пользовательские обработчики запросов для указанного маршрута с использованием веб-API Request и Response.

Важно знать: Обработчики маршрутов доступны только внутри директории app. Они являются эквивалентом API Routes внутри директории pages, что означает, что вам не нужно использовать API Routes и Route Handlers вместе.

Соглашение

Обработчики маршрутов определяются в файле route.js|ts внутри директории app:

export async function GET(request: Request) {}

export async function GET(request) {}

Обработчики маршрутов могут быть вложены в любую часть директории app, аналогично page.js и layout.js. Однако не может быть файла route.js на том же уровне сегмента маршрута, что и page.js.

Поддерживаемые HTTP-методы

Поддерживаются следующие HTTP-методы: GET, POST, PUT, PATCH, DELETE, HEAD и OPTIONS. Если вызывается неподдерживаемый метод, Next.js вернет ответ 405 Method Not Allowed.

Расширенные API `NextRequest` и `NextResponse`

Помимо поддержки нативных API Request и Response, Next.js расширяет их с помощью NextRequest и NextResponse, предоставляя удобные вспомогательные методы для сложных случаев использования.

Поведение

Кэширование

Обработчики маршрутов по умолчанию не кэшируются. Однако вы можете включить кэширование для методов 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 })
}

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

Важно знать: Другие поддерживаемые HTTP-методы не кэшируются, даже если они находятся в одном файле с кэшируемым методом GET.

Специальные обработчики маршрутов

Специальные обработчики маршрутов, такие как sitemap.ts, opengraph-image.tsx, icon.tsx и другие файлы метаданных, по умолчанию остаются статическими, если они не используют динамические API или опции динамической конфигурации.

Разрешение маршрутов

Вы можете рассматривать route как примитив самого низкого уровня для маршрутизации.

Они не участвуют в макетах или клиентской навигации, как page.
Не может быть файла route.js на том же маршруте, что и page.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-методы для этого маршрута.

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

// ❌ Конфликт
// `app/route.ts`
export async function POST(request: Request) {}

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

// ❌ Конфликт
// `app/route.js`
export async function POST(request) {}

Примеры

Следующие примеры показывают, как комбинировать обработчики маршрутов с другими API и функциями Next.js.

Ревалидация кэшированных данных

Вы можете ревалидировать кэшированные данные с помощью инкрементальной статической регенерации (ISR):

export const revalidate = 60

export async function GET() {
  const data = await fetch('https://api.vercel.app/blog')
  const posts = await data.json()

  return Response.json(posts)
}

export const revalidate = 60

export async function GET() {
  const data = await fetch('https://api.vercel.app/blog')
  const posts = await data.json()

  return Response.json(posts)
}

Куки (Cookies)

Вы можете читать или устанавливать куки с помощью cookies из next/headers. Эта серверная функция может быть вызвана непосредственно в обработчике маршрута или вложена в другую функцию.

Альтернативно, вы можете вернуть новый Response с заголовком Set-Cookie.

import { cookies } from 'next/headers'

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

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

import { cookies } from 'next/headers'

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

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

Вы также можете использовать базовые веб-API для чтения куки из запроса (NextRequest):

import { type NextRequest } from 'next/server'

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

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

Заголовки (Headers)

Вы можете читать заголовки с помощью headers из next/headers. Эта серверная функция может быть вызвана непосредственно в обработчике маршрута или вложена в другую функцию.

Экземпляр headers доступен только для чтения. Чтобы установить заголовки, вам нужно вернуть новый Response с новыми headers.

import { headers } from 'next/headers'

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

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

import { headers } from 'next/headers'

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

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

Вы также можете использовать базовые веб-API для чтения заголовков из запроса (NextRequest):

import { type NextRequest } from 'next/server'

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

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

Перенаправления (Redirects)

import { redirect } from 'next/navigation'

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

import { redirect } from 'next/navigation'

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

Динамические сегменты маршрутов

Обработчики маршрутов могут использовать Динамические сегменты для создания обработчиков запросов из динамических данных.

export async function GET(
  request: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params // 'a', 'b' или 'c'
}

export async function GET(request, { params }) {
  const { slug } = await params // 'a', 'b' или 'c'
}

Маршрут	Пример URL	`params`
`app/items/[slug]/route.js`	`/items/a`	`Promise<{ slug: 'a' }>`
`app/items/[slug]/route.js`	`/items/b`	`Promise<{ slug: 'b' }>`
`app/items/[slug]/route.js`	`/items/c`	`Promise<{ slug: 'c' }>`

Параметры URL-запроса

Объект запроса, передаваемый в обработчик маршрута, является экземпляром NextRequest, который включает несколько удобных методов, например, для более удобной работы с параметрами запроса.

import { type NextRequest } from 'next/server'

export function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const query = searchParams.get('query')
  // query будет "hello" для /api/search?query=hello
}

export function GET(request) {
  const searchParams = request.nextUrl.searchParams
  const query = searchParams.get('query')
  // query будет "hello" для /api/search?query=hello
}

Потоковая передача (Streaming)

Потоковая передача часто используется в сочетании с большими языковыми моделями (LLM), такими как OpenAI, для генерации контента с помощью ИИ. Узнайте больше о AI SDK.

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

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

Эти абстракции используют веб-API для создания потока. Вы также можете использовать базовые веб-API напрямую.

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

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

Тело запроса (Request Body)

Вы можете прочитать тело Request с помощью стандартных методов веб-API:

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

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

Форма данных (FormData) в теле запроса

Вы можете прочитать FormData с помощью функции request.formData():

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

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 являются строками, вы можете использовать zod-form-data для валидации запроса и получения данных в предпочитаемом формате (например, number).

CORS

Вы можете установить заголовки CORS для конкретного обработчика маршрута с помощью стандартных методов веб-API:

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

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 к нескольким обработчикам маршрутов, вы можете использовать Middleware или файл next.config.js.

Альтернативно, ознакомьтесь с нашим примером CORS.

Вебхуки (Webhooks)

Вы можете использовать обработчик маршрута (Route Handler) для получения вебхуков от сторонних сервисов:

export async function POST(request: Request) {
  try {
    const text = await request.text()
    // Обработка данных вебхука
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    })
  }

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

export async function POST(request) {
  try {
    const text = await request.text()
    // Обработка данных вебхука
  } catch (error) {
    return new Response(`Webhook error: ${error.message}`, {
      status: 400,
    })
  }

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

Важно отметить, что в отличие от API-маршрутов (API Routes) в Pages Router, здесь не требуется использовать bodyParser или дополнительные настройки.

Ответы без пользовательского интерфейса (Non-UI Responses)

Обработчики маршрутов можно использовать для возврата контента, не связанного с UI. Обратите внимание, что для sitemap.xml, robots.txt, иконок приложения и open graph изображений предусмотрена встроенная поддержка.

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>`,
    {
      headers: {
        'Content-Type': 'text/xml',
      },
    }
  )
}

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'

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.

route.js

API-справочник для специального файла route.js.

Обработчики маршрутов (Route Handlers)

route.js

On this page