Server Actions в Next.js 13.4 — руководство

iMac на столе с открытым редактором кода и приложением Next.js

Server actions в Next.js 13.4 позволяют выносить обработку мутаций (например, сохранение формы) полностью на сервер внутри серверных компонентов. Это уменьшает количество клиентского JavaScript, повышает безопасность и упрощает архитектуру по сравнению с отдельными API-роутами. В статье — пример кода, объяснение механики кеширования и повторной валидации, рекомендации по безопасности и чек-листы для миграции.

Important: server actions в 13.4 пока считаются экспериментальной/альфа-функциональностью. Для производства рекомендуем тестировать на более поздних версиях и следить за изменениями API.

Краткое определение

Server action — это функция, помеченная директивой “use server”, которая выполняется на сервере и может вызываться из серверных или клиентских компонентов. Она заменяет необходимость писать отдельные API-роуты для простых мутаций.

Почему это важно

Меньше клиентского JavaScript: логика мутаций остаётся на сервере.
Безопаснее: можно безопасно использовать переменные окружения и подключение к БД.
Проще: нет лишних API-эндпоинтов для простых операций.

Быстрый пример: создание поста

Ниже — минимальный пример формы и server action для создания поста. Обратите внимание, что код запускается на сервере и использует revalidateTag для обновления кэша.

Импорты:

import Link from "next/link"
import FormGroup from "@/components/FormGroup"
import { revalidateTag } from "next/cache"
import { redirect } from "next/navigation"

Server action, выполняемая на сервере:

async function createPost(data) {
  "use server"
  const title = data.get("title")
  const body = data.get("body")

  await fetch("http://127.0.0.1/posts", {
    headers: { "Content-Type": "application/json" },
    method: "POST",
    body: JSON.stringify({ title, body })
  })

  // Обновляем тэг кэша, чтобы страницы с тегом "posts" подтянули новые данные
  revalidateTag("posts")

  // Перенаправляем на домашнюю страницу
  redirect("/")
}

Компонент формы (серверный компонент с action):

export default function NewPostForm() {
  return (
    
      
        
          Title
          
        
      

      
        
          Body
          
        
      

      
        
      
    
  )
}

Примечание: форма не содержит логики создания поста — только action, который вызывает функцию createPost. Эта функция помечена “use server” и выполняется на сервере.

Как работает повторная валидация (revalidation)

В серверном компоненте, который рендерит список постов, вы, вероятно, делаете fetch с опцией next, указывающей тэг и период повторной валидации:

export default async function Posts() {
  const posts = await getPosts()

  return (
    
      {posts.map(post => {
        return 
      })}
    
  )
}

async function getPosts() {
  const res = await fetch("https://127.0.0.1/posts?sort=title", {
    next: { tags: ["posts"], revalidate: 3600 }
  })

  return res.json()
}

Опция revalidate: 3600 означает, что Next.js считает данные валидными до 3600 секунд (1 час). Однако при создании нового поста вы можете принудительно пометить тэг как устаревший через revalidateTag(“posts”) — тогда Next.js сделает повторный fetch и отобразит новый пост почти сразу.

Доказательство выполнения на сервере

Чтобы удостовериться, что функция выполняется на сервере, добавьте в неё логирование:

console.log("Running on the server")

Если при сабмите поста сообщение появится в серверном терминале, это подтверждает серверное выполнение. Если оно появится в консоли браузера — значит, действие выполнялось на клиенте.

Когда server actions помогают, а когда нет

Когда стоит использовать:

Простые формы и CRUD-операции, где логика хорошо укладывается в одну функцию.
Операции, требующие доступа к секретам (.env, ключи, подключения к БД).
Когда нужно минимизировать клиентский JS и упростить архитектуру.

Когда стоит отказаться:

Сложная бизнес-логика, требующая отдельного бэкенд-сервиса или сложной валидации.
Если вы уже имеете зрелую инфраструктуру API (GraphQL/REST) с политиками авторизации, мониторинга и версионирования.
Требуется трансляция работы в фоновые задачи или очереди — лучше оставить это в бекенде.

Альтернативы и сравнение подходов

API-роуты (REST/GraphQL):
- Подходящи для комплексных API, версионирования и внешних клиентов.
- Даёт единый контракт для мобильных и сторонних клиентов.
Клиентские мутации (fetch/Axios из клиента):
- Подходит, когда вы хотите максимально интерактивный интерфейс и живые отклики на стороне клиента.
- Требует больше клиентского JS и тщательной работы с безопасностью.
Server actions:
- Просты для внутренних операций и ускоряют разработку серверных компонентов.
- Могут заменить небольшие API-роуты и упростить формы.

Выбор основан на зрелости проекта, требованиях к безопасности, масштабируемости и наличию сторонних клиентов.

Ментальные модели и эвристики

“Action as handler”: думайте о server action как о серверном обработчике формы, встроенном рядом с компонентом.
“Тэг — это связка данных”: тэги кэша (например, “posts”) представляют логические наборы данных; инвалидируйте тэг при изменении данных.
“Клиент — только UI”: чем больше логики вы переносите на сервер, тем легче контролировать расходы на клиент и стандартные слабые места безопасности.

Практические советы по безопасности

Никогда не возвращайте секреты из server actions.
Валидируйте и санитизируйте входные данные на сервере.
Применяйте проверку авторизации внутри server action (проверяйте сессию/токен).
Рассмотрите rate limiting и защиту от брутфорса для критичных эндпоинтов.

Notes: использование серверных действий делает безопасным чтение переменных окружения и подключение к БД, потому что код не попадёт в бандл на клиент.

Чек-лист перед миграцией формы на server actions

Для разработчика:

Убедиться, что функция проста и не требует фоновых задач.
Добавить в action директиву “use server”.
Проверить авторизацию и валидацию внутри action.
Тестировать локально и смотреть логи сервера.

Для ревьюера:

Нет утечек секретов в ответах.
Корректная обработка ошибок и возвраты статусов/редиректов.
Использование revalidateTag, если нужен немедленный апдейт UI.

Миграция: пошаговый план (мини-руководство)

Выделите простые формы или действия, подходящие для переноса (создание, обновление, удаление).
Создайте server action рядом с компонентом и пометьте “use server”.
Перенесите логику в action и замените клиентские fetch/axios/submit на form action или вызов action.
Добавьте проверки авторизации и валидацию.
Используйте revalidateTag для обновления связанных серверных компонент.
Тестируйте: unit, интеграционные тесты и ручное тестирование через UI.

Примеры отказа: когда server actions не сработают

Если требуется поддержка сторонних клиентов (мобильные приложения) — нужен открытый API.
Если нужно масштабировать обработчики в отдельные микросервисы.
Если операции должны выполняться асинхронно в очереди (например, отправка большого количества писем) — лучше вынести в background worker.

Совместимость, версии и миграционные советы

Server actions появились в Next.js 13.4 на базе React Actions. API может меняться в следующих версиях.
Для продакшена рекомендуем использовать более новые стабильные версии Next.js, следить за релиз-ноутами и тестировать поведение revalidateTag и директивы “use server”.

Краткая справка-терминология

Server action: серверная функция с директивой “use server”; выполняется на сервере.
revalidateTag: инструмент для инвалидирования кэша по тэгу и принудительного рефетча.
next.fetch revalidate: опция в fetch для серверных компонентов, задающая TTL кэша.

Частые вопросы

Можно ли вызывать server action из клиентского компонента?

Да — Next.js позволяет вызывать server actions и из клиентских компонентов, но при этом вызов будет перенаправлять данные на сервер и запускаться там. Формы с атрибутом action удобнее использовать из серверных компонентов.

Поддерживаются ли GraphQL-мутации через server actions?

Да. Server action может выполнить fetch к GraphQL-эндпойнту или напрямую использовать серверную библиотеку для GraphQL (например, выполнить мутацию через Apollo Server на сервере).

Что делать с ошибками в action?

Обрабатывайте ошибки в server action и возвращайте понятные редиректы или сообщения об ошибках. Для детального контроля используйте собственную стратегию обработки исключений.

Краткое резюме

Server actions упрощают мутации в Next.js, уменьшают клиентский код и повышают безопасность.
Используйте revalidateTag для быстрой синхронизации данных после мутаций.
Не применяйте server actions для сложных backend-процессов или внешних клиентов — там лучше API или отдельные сервисы.

Summary

Server actions позволяют вызывать серверный код прямо из компонентов.
revalidateTag — ключ к моментальному обновлению связанных страниц.
Тестируйте и применяйте дополнительные меры безопасности при работе с секретами и подключениями к БД.

Если хотите, могу подготовить шаблон миграции для конкретного проекта (React SPA → Next.js) или список acceptance-тестов для перехода форм на server actions.