re:re:actable
Урок 022 минуты чтения

Server Actions и API-маршруты

На этой странице
Кратко

Server Action связывает серверную мутацию с интерфейсом Next.js. API-маршрут предоставляет явный HTTP-контракт для браузера, внешнего приложения или сервиса.

Вопрос

Когда выбирать Server Action, а когда Route Handler или API Route?

Основная идея

В App Router HTTP-обработчики называются Route Handlers, в Pages Router — API Routes. Обе модели позволяют задать URL, HTTP-методы, статусы и формат ответа.

ЗадачаПодход
Сохранение формы внутри Next.jsServer Action
Мобильный клиент запрашивает данныеHTTP API
Внешний сервис отправляет вебхукHTTP API
Кнопка меняет данные и обновляет страницуServer Action
Нужен определенный статус или файл в ответеRoute Handler

Action тоже доступен через сетевой механизм Next.js. Утверждение «у него вообще нет endpoint и его нельзя вызвать извне» создает ложное чувство безопасности. Его внутренний протокол просто не предназначен для стабильного публичного REST API.

Пример: открытое чтение и внутренняя настройка

Два независимых примера для Next.js 16 App Router:

// app/api/languages/route.ts
export async function GET() {
  return Response.json({ languages: ["ru", "en"] });
}

Этот адрес /api/languages возвращает JSON и может использоваться внешним клиентом.

// app/actions.ts
"use server";
 
import { cookies } from "next/headers";
 
export async function saveLanguage(formData: FormData) {
  const language = formData.get("language");
  if (language !== "ru" && language !== "en") {
    throw new Error("Недопустимый язык");
  }
  (await cookies()).set("language", language, {
    path: "/",
    httpOnly: true,
    sameSite: "lax",
    secure: process.env.NODE_ENV === "production",
  });
}

Эту функцию можно передать в <form action={saveLanguage}>. Форма отправит FormData с полем language, а Action сохранит настройку текущего браузера.

Что важно помнить

И HTTP-обработчик, и Action выполняются на сервере, но оба должны проверять недоверенные входные данные. Для защищенной мутации также нужны аутентификация и авторизация: кто пользователь и может ли он менять именно эту запись.

Actions обычно используют для мутаций. Основную загрузку страницы удобнее выполнять непосредственно в Server Components.

Мини-шпаргалка

  • Action: изменение данных из интерфейса.
  • Route Handler: явный HTTP API.
  • Оба подхода требуют серверных проверок.

Документация

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

Поиск

Поиск по урокам