Серверные экшены: RPC поверх POST, который надо считать публичным эндпоинтом

Механика: во что на самом деле компилируется ‘use server’

Директива 'use server' — в начале async-функции или целого файла — велит бандлеру вырезать функцию из клиентского графа и заменить каждую клиентскую ссылку на неё стабильным id. Вызов экшена из браузера отправляет POST на URL текущей страницы с заголовком Next-Action, несущим этот id, и аргументами в теле; сервер маршрутизирует запрос в скомпилированную функцию, выполняет её и стримит обратно возвращаемое значение вместе с обновлённым RSC-payload. Это RPC со спрятанной обвязкой: ни файла маршрута, ни вызова fetch, ни именования эндпоинта — но провод никуда не делся, и всё, что его пересекает, подчиняется правилам провода.

Аргументы и возвращаемые значения должны сериализоваться протоколом React — это надмножество JSON, понимающее Date, Map, Set, FormData, типизированные массивы и промисы, но не экземпляры классов, не функции и не что-либо с методами. Верните Prisma-модель с полем-классом Decimal — получите runtime-ошибку сериализации; привычка — возвращать плоские DTO (формы вида id плюс name, собранные намеренно). Замыкания работают — экшен, определённый внутри серверного компонента, может захватить переменные из его области видимости, — и Next шифрует захваченные значения ключом конкретной сборки, прежде чем пропустить их через клиент. Но шифрование — не авторизация: никогда не считайте замкнутое значение секретом, который пользователю нельзя видеть, и не доверяйте ему как защищённому от подмены входу.

Ещё одно правило провода, которое удивляет команды: один клиент выполняет экшены последовательно — вызовы становятся в очередь, и медленный экшен блокирует стоящие за ним. Экшены — примитив мутаций, а не универсальный механизм параллельной загрузки данных.

// app/actions.ts
'use server';

import { z } from 'zod';
import { revalidateTag } from 'next/cache';
import { getSession } from '~/lib/auth';

const Input = z.object({ projectId: z.string().uuid(), name: z.string().min(1).max(120) });

export async function renameProject(raw: unknown) {
  // 1. Аутентификация + авторизация ВНУТРИ экшена — единственный существующий шлагбаум.
  const session = await getSession();
  if (!session) throw new Error('Unauthenticated');

  // 2. Валидация: провод нетипизирован; TypeScript-сигнатуры — не валидация.
  const input = Input.parse(raw);
  const project = await db.project.findUnique({ where: { id: input.projectId } });
  if (project?.ownerId !== session.userId) throw new Error('Forbidden');

  // 3. Мутация, затем уведомление кешей.
  await db.project.update({ where: { id: input.projectId }, data: { name: input.name } });
  revalidateTag(`project-${input.projectId}`);
  return { ok: true as const };
}

Прогрессивное улучшение: формы, работающие до JavaScript

Передайте экшен форме — <form action={renameProject}> — и форма работает до гидратации: при выключенном, медленном или ещё не доехавшем JS браузер делает обычный form POST, Next маршрутизирует его в экшен, и страница перерендеривается с результатом. На гидрированной странице та же форма апгрейдится до RPC-пути без полной перезагрузки. useActionState надстраивает состояние (предыдущий результат, флаг pending и улучшенный экшен), а useFormStatus отдаёт дочернему компоненту pending-состояние для блокировки кнопки отправки.

На медленных сетях это реальный, измеримый выигрыш: пользователь на 3G, к которому 200 КБ JS ещё не доехали, всё равно может отправить форму чекаута. Но гарантия узкая — она покрывает только отправку форм. Экшен, повешенный на onClick, выстреливаемый из useEffect или вызываемый императивно, нуждается в гидрированном JavaScript, как любой другой обработчик. Команды, рассказывающие «наше приложение работает без JS, потому что мы на серверных экшенах», при этом дёргая каждую мутацию из кнопок с click-обработчиками, имеют прогрессивное улучшение в буклете, а не в продукте.

Компромисс: путь формы ограничивает входы FormData — по сути строками, — а значит, парсинг и приведение типов на сервере (zod с z.coerce отрабатывает свой хлеб). RPC-путь принимает богатые сериализуемые аргументы, но отдаёт гарантию без-JS. Выбирайте по мутации: чекаут и логин тяготеют к формам, drag-and-drop-сортировка — очевидно нет.

Безопасность: каждый экшен — публичный эндпоинт

История пентеста обобщается в чек-лист. Аутентифицируйте и авторизуйте внутри каждого экшена — экшен достижим независимо от того, какие компоненты рендерились, так что тело функции — единственный существующий шлагбаум. Валидируйте каждый аргумент — сигнатура TypeScript есть фикция этапа компиляции; в рантайме тело POST — это байты под контролем атакующего, поэтому парсите схемой до прикосновения к базе, ровно как в route handler. Когда пишете экшен, спросите себя: если залогиненный пользователь переиграет этот POST с произвольным projectId — что случится? Этот вопрос обнаруживает брешь в авторизации до пентестера. Считайте экспортированные экшены своей API-поверхностью: Next.js действительно выкидывает id экшенов, на которые нет ссылок, а id недетерминированы между сборками — но «неугадываемый id» это обскурность, а не контроль доступа, потому что всякий, кому UI легитимно служит, видит id в собственном network tab.

Часть ноши фреймворк несёт сам: серверные экшены принимают только POST, и Next сравнивает заголовок Origin с Host, отклоняя расхождения — солидная same-site CSRF-защита из коробки (с конфигом allowedOrigins для прокси-схем, где они легитимно различаются). Точно понимайте, что это покупает: она останавливает межсайтовую подделку и ничего не делает с вашими собственными аутентифицированными пользователями, вызывающими найденные ими экшены, — это задача авторизации, которую решает только ваш код.

Сценарий отказа: более тонкая версия пентест-бага — экшен, авторизующий тип сущности, но не экземпляр: проверяет «залогинен» и дальше обновляет любой пришедший projectId. IDOR (Insecure Direct Object Reference — небезопасная прямая ссылка на объект), массово присваиваемый через типизированную на вид сигнатуру функции. Проверка владения в примере кода (project.ownerId !== session.userId) — та самая строка, которую пропускают на код-ревью, потому что функция «вызывается только со страницы владельца».

Ревалидация после мутации — и когда предпочесть route handlers

Мутация, которая прошла, но оставила протухшие кеши, в баг-репорте неотличима от мутации, которая не прошла («я сохранил, и ничего не изменилось»). Завершайте каждый меняющий состояние экшен объявлением того, что он инвалидировал: revalidatePath или revalidateTag чистит серверные кеши и — поскольку выполнен внутри экшена — инвалидирует клиентский Router Cache мутировавшего пользователя, так что UI перед его глазами обновляется тем же круговым путём. redirect() компонуется с этим для сценария «создал — смотришь». Забытая строка ревалидации — самый частый production-баг серверных экшенов, и в разработке он невидим, потому что кеширование там почти выключено.

Серверные экшены — для мутаций вашего собственного приложения из вашего собственного React-дерева. Предпочитайте route handler, когда вызывающий — не ваш UI: вебхуки от Stripe или CMS, мобильные клиенты, сторонние интеграции — они не могут адресовать непрозрачный, меняющийся от сборки к сборке id экшена и нуждаются в стабильном URL с явными методами. Route handlers выигрывают и для GET-эндпоинтов (экшены — POST-мутации по дизайну), для ответов, не сериализуемых React (файлы, кастомные заголовки, редиректы с конкретными статус-кодами), и для высококонкурентной клиентской стрельбы — экшены одного клиента выполняются последовательно, а запросы к route handler идут параллельно. Разумное командное правило: экшены — для внутриприложенческих мутаций из форм и кнопок, route handlers — для всего, у чего есть внешний вызывающий или строчка в OpenAPI.