Что такое Server Actions в Next.js-подобных React-фреймворках и как их использовать?

Что это такое

Server Actions — это функции, которые физически выполняются только на сервере, но их можно импортировать и вызывать из клиентского кода так, будто это обычный JS. Фреймворк (Next.js App Router, Remix-подобные решения) под капотом превращает такой вызов в сетевой запрос (RPC поверх POST), сериализует аргументы и результат, и гарантирует, что тело функции никогда не попадёт в клиентский бандл.

Объявляются директивой "use server" — либо в начале файла (все экспортируемые функции становятся actions), либо прямо внутри функции, объявленной в серверном компоненте.

Зачем они нужны

• Убирают необходимость вручную писать route.ts/API-эндпоинт под каждую мутацию.
• Дают типобезопасность end-to-end: сигнатура функции — это и есть контракт.
• Поддерживают progressive enhancement — форма с action={serverAction} работает даже без JS, потому что браузер делает обычный submit.
• Интегрируются с кэшем фреймворка: revalidatePath/revalidateTag позволяют точечно инвалидировать данные после мутации.

Как использовать

1. В отдельном файле — удобно для переиспользуемых actions:

// actions/todos.ts
"use server";

import { db } from "@/lib/db";
import { revalidatePath } from "next/cache";

export async function addTodo(formData: FormData) {
  const title = formData.get("title");
  if (typeof title !== "string" || title.trim().length === 0) {
    return { error: "Название обязательно" };
  }

  await db.todo.create({ data: { title } });
  revalidatePath("/todos"); // сбрасываем кэш страницы со списком
}

2. Инлайново в серверном компоненте:

export default function TodosPage() {
  async function addTodo(formData: FormData) {
    "use server";
    // логика мутации
  }

  return (
    <form action={addTodo}>
      <input name="title" />
      <button type="submit">Добавить</button>
    </form>
  );
}

3. Вызов вне форм — из клиентского компонента как обычная async-функция, например по клику, с useTransition для отображения состояния загрузки, и useActionState (бывший useFormState) для отображения ошибок валидации без лишнего client state.

Что важно на senior-уровне

• Безопасность: action — это фактически публичный HTTP-эндпоинт. Внутри обязательно нужно проверять авторизацию и права доступа, а не полагаться на то, что кнопка скрыта в UI.
• Валидация на сервере — данные от клиента нельзя доверять; входные аргументы нужно валидировать (например, через zod), включая случай прямого вызова action в обход формы.
• Сериализация — аргументы и возврат должны быть сериализуемыми (без функций, классов, циклических ссылок).
• Кэш и ревалидация — нужно понимать разницу между revalidatePath и revalidateTag, иначе после мутации UI покажет устаревшие данные.
• Идемпотентность и повторные сабмиты — формы могут быть отправлены повторно (двойной клик, ретрай сети), стоит закладывать защиту от дублей на уровне БД/бизнес-логики.

Ограничения

Server Actions — не замена полноценному REST/GraphQL API для внешних клиентов (мобильных приложений, сторонних интеграций): это внутренний механизм связи UI с сервером конкретного фреймворка.