Руководство для начинающих по удалённым функциям в SvelteKit

Вы создавали приложения на SvelteKit с эндпоинтами +server.ts и form actions. Они работают, но вы пишете шаблонный код: парсите тела запросов, вручную валидируете входные данные и поддерживаете отдельные определения типов для клиента и сервера. Удалённые функции SvelteKit (Remote Functions) предлагают другой подход — типобезопасные серверные вызовы без церемоний традиционных API-эндпоинтов.

Это руководство объясняет, что такое удалённые функции, когда использовать каждый тип и какие компромиссы следует понимать перед их внедрением.

Что такое удалённые функции SvelteKit?

Удалённые функции позволяют писать серверный код, который клиенты вызывают как обычные функции. За кулисами SvelteKit компилирует их в HTTP-эндпоинты и генерирует fetch-обёртки для клиента. Вы получаете сквозную типобезопасность без создания и поддержки традиционных API-маршрутов.

Представьте это как SvelteKit, обрабатывающий сантехнику между вашим фронтендом и бэкендом. Вы пишете функцию в файле .remote.ts, а SvelteKit обрабатывает сериализацию, генерацию эндпоинтов и вывод типов.

Если вам нужна официальная справка, эта функция задокументирована в документации SvelteKit в разделе Remote Functions: https://kit.svelte.dev/docs/remote-functions

Включение экспериментальной функции

Удалённые функции требуют явного включения через kit.experimental.remoteFunctions в вашем svelte.config.js:

const config = {
  kit: {
    experimental: {
      remoteFunctions: true
    }
  }
};

export default config;

Если вы хотите использовать await напрямую в компонентах Svelte, вам также потребуется отдельно включить экспериментальную поддержку async в Svelte. Это не обязательно — удалённые функции работают и без этого — но это упрощает код компонентов.

Четыре типа серверных функций SvelteKit

Удалённые функции бывают четырёх видов, каждый предназначен для конкретных случаев использования.

Query: получение динамических данных

Используйте query при чтении данных из баз данных, API или любых серверных ресурсов. Запросы могут выполняться во время рендеринга компонента и дедуплицируются и группируются в рамках одного жизненного цикла рендеринга.

import { query } from '$app/server';
import { db } from '$lib/db';
import { posts } from '$lib/schema';

export const getPosts = query(async () => {
  return await db.select().from(posts);
});

Для критичных к производительности сценариев query.batch группирует несколько одновременных вызовов в один запрос — решая проблему n+1 без ручной оптимизации.

Form: мутации данных с прогрессивным улучшением

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

Разверните возвращаемый объект на ваш элемент <form>, и SvelteKit автоматически обработает как улучшенные, так и неулучшенные отправки.

Command: гибкие мутации

command работает как form, но не привязан к элементам формы. Используйте его для кликов по кнопкам, действий drag-and-drop или любых мутаций, инициируемых вне контекста формы.

В отличие от форм, команды требуют JavaScript. Выбирайте form, когда важно прогрессивное улучшение. Выбирайте command, когда нужна гибкость.

Prerender: статические данные во время сборки

prerender получает данные во время сборки, а не во время выполнения. Результаты кэшируются во время сборки и обслуживаются через кэш платформы или CDN. Используйте это для конфигурации, контента CMS, который меняется только при развёртывании, или любых данных, не требующих обновлений в реальном времени.

Важное ограничение: вы не можете использовать query на полностью предрендеренных страницах, поскольку запросы по своей природе динамичны.

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

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

SvelteKit ожидает, что вы будете валидировать аргументы с помощью библиотек Standard Schema, таких как Zod или Valibot (инициатива “Standard Schema” задокументирована на https://standardschema.dev):

import { query } from '$app/server';
import * as v from 'valibot';
import { db } from '$lib/db';
import { posts } from '$lib/schema';

const Params = v.object({
  slug: v.string()
});

export const getPost = query(Params, async ({ slug }) => {
  return await db.select().from(posts).where(eq(posts.slug, slug));
});

Без валидации злоумышленники могут отправлять произвольные данные на ваши эндпоинты. SvelteKit обычно возвращает ошибки уровня 400 при сбоях валидации, избегая утечки информации.

Поддерживайте SvelteKit в актуальном состоянии

Прошлые версии имели уязвимости безопасности, затрагивающие удалённые функции, включая проблемы DoS. Следите за актуальностью релизов, особенно пока функция остаётся экспериментальной (по состоянию на SvelteKit 2.x).

Компромиссы, которые следует учитывать

Удалённые функции сокращают шаблонный код, но не являются магией. Учитывайте эти ограничения:

• Расположение файлов имеет значение: файлы .remote.ts размещаются где угодно в src, кроме src/lib/server
• Кэширование prerender: кэширование браузера и CDN означает устаревшие данные до повторного развёртывания
• Экспериментальный статус: API могут измениться, и ошибки ожидаемы

Удалённые функции работают лучше всего, когда вы хотите типобезопасную коммуникацию клиент-сервер без поддержки отдельных определений эндпоинтов. Они не замена каждому файлу +server.ts — сложные потоки аутентификации или обработчики вебхуков третьих сторон могут всё ещё требовать традиционных эндпоинтов.

Когда использовать каждый тип функции

Заключение

Удалённые функции SvelteKit упрощают границу между клиентским и серверным кодом. Они устраняют ручное обслуживание эндпоинтов, обеспечивая встроенную валидацию и типобезопасность. Начните с query для получения данных, добавьте form для пользовательского ввода и обращайтесь к command или prerender, когда эти конкретные паттерны соответствуют вашим потребностям.

Функция экспериментальная — ожидайте изменений. Но для разработчиков SvelteKit, уставших от шаблонного кода эндпоинтов, удалённые функции предлагают убедительную альтернативу, которую стоит изучить.

Часто задаваемые вопросы

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.