Next.js Route Handlers: Создание API Endpoints в App Router

🎯 1. Введение: Что такое обработчики маршрутов?

Обработчики маршрутов (Route Handlers) — это мощный механизм в Next.js, который позволяет создавать собственные API-эндпоинты прямо внутри Next.js приложения. Это способ создавать пользовательские обработчики запросов для конкретных URL-адресов, используя стандартные веб-интерфейсы Request и Response.

Хотя Route Handlers — универсальный инструмент для создания API, они также незаменимы для:

• Создания мок-эндпоинтов на сервере
• Тестирования стратегий получения данных
• Тестирования ревалидации данных

🚀 2. Ключевые сценарии использования: Зачем нужны Route Handlers?

📊 1. Прямая работа с данными

• Взаимодействие с источниками данных (базы данных, локальные файлы)
• Чтение данных из локальных файлов (например, JSON)
• Вынос логики доступа к данным за пределы UI-компонентов

🔄 2. Создание прокси или шлюза

• Паттерн back-to-back запросы
• Сокрытие API-ключей и секретов (вызов на сервере, а не клиенте)
• Упрощение сложных API (предоставление фронтенду только нужных данных)

🏗️ 3. Делегирование серверной логики

• Соответствие Принципу единственной ответственности (Single Responsibility Principle)
• Фокус компонентов страниц на рендеринге UI
• Выделение бизнес-логики в отдельные обработчики
• Чище, модульнее, проще в поддержке

🛠️ 3. Пошаговое руководство: Создаем первый эндпоинт

📁 3.1. Файловая структура и именование

📌 Правила создания:

1. Специальное имя файла: route.ts (или .js)
2. URL = Путь к файлу:

• app/api/title/route.ts → /api/title

3. Важное ограничение: На одном уровне с route.ts не должно быть page.ts/page.tsx

💻 3.2. Написание функции-обработчика

Внутри файла route.ts нужно экспортировать асинхронную функцию, названную в честь HTTP-метода, который она будет обрабатывать.

import fs from "fs/promises"
import path from "path"
 
export async function GET() {
  const getParsedData = async () => {
    const filePath = path.join(process.cwd(), "public", "data.json")
    try {
      const data = await fs.readFile(filePath)
      return JSON.parse(data.toString())
    } catch {
      return { title: "no title" }
    }
  }
 
  const data = await getParsedData()
  return Response.json(data)
}

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

Next.js поддерживает следующие HTTP-методы для именования функций-обработчиков:

📡 4. Как обратиться к эндпоинту из приложения

Для получения данных из созданного эндпоинта внутри страницы или компонента Next.js используется стандартный fetch API.

📝 Пример кода: Запрос данных в серверном компоненте

export const revalidate = 15
 
export default async function Books() {
  const { title } = await fetch("http://localhost:3000/api/title").then((res) => res.json())
 
  const data = await fetch("https://jsonplaceholder.typicode.com/todos")
  const todolists = await data.json()
 
  return (
    <div className={styles.page}>
      <main className={styles.main}>
        <div style={{ marginBottom: "30px", color: "yellow" }}>{title}</div>
        <Todolists todolists={todolists} />
      </main>
    </div>
  )
}

🎯 Ключевая идея

По сути, это запрос "к самому себе" 🔄. Однако важно понимать, что:

• 🖥️ На сервере: Когда и серверный компонент, и эндпоинт выполняются на сервере Next.js, этот fetch-запрос не создает реального сетевого вызова через интернет.
• ⚡ Оптимизация: Next.js оптимизирует его до прямого вызова функции внутри серверного процесса, что делает его чрезвычайно эффективным.
• 🌍 Переносимость: Использование относительных путей (например, /api/title) является лучшей практикой, так как это делает код переносимым между различными окружениями (development, production).

🔍 5. Доступ к данным запроса: Headers и Cookies

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

📋 Функции для работы с запросом

📝 Пример: Использование headers()

import fs from "fs/promises"
import { headers } from "next/headers"
import path from "path"
 
export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get("user-agent")
 
  console.log("userAgent", userAgent)
 
  const getParsedData = async () => {
    const filePath = path.join(process.cwd(), "public", "data.json")
    try {
      const data = await fs.readFile(filePath)
      return JSON.parse(data.toString())
    } catch {
      return { title: "no title" }
    }
  }
 
  const data = await getParsedData()
  return Response.json(data)
}

📝 Пример: Использование cookies()

import fs from "fs/promises"
import { cookies, headers } from "next/headers"
import path from "path"
 
export async function GET() {
  const headersList = await headers()
  const userAgent = headersList.get("user-agent")
 
  const cookiesList = await cookies()
 
  console.log("cookiesList", cookiesList)
 
  const getParsedData = async () => {
    const filePath = path.join(process.cwd(), "public", "data.json")
    try {
      const data = await fs.readFile(filePath)
      return JSON.parse(data.toString())
    } catch {
      return { title: "no title" }
    }
  }
 
  const data = await getParsedData()
  return Response.json(data)
}

✅ 6. Ключевые выводы

1. 🚀 Создание API на лету

Обработчики маршрутов — это встроенный в Next.js способ быстрого создания API-эндпоинтов с помощью простого соглашения об именовании файлов (route.ts).

2. 🗂️ Структура папок = URL

Путь к эндпоинту напрямую определяется его местоположением в файловой системе внутри директории app, что делает навигацию и структуру проекта интуитивно понятными.

3. 🧩 Инкапсуляция и повторное использование

Они позволяют инкапсулировать сложную серверную логику (работа с БД, сторонними API) в чистые, переиспользуемые эндпоинты, отделяя логику данных от логики представления.