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.js | Server 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.
- Оба подхода требуют серверных проверок.