Laravel Wayfinder Когда бэкенд и фронтенд говорят на одном языке

Знакомая ситуация? Вы увлеченно пишете фронтенд на TypeScript, а где-то в недрах бэкенда на Laravel меняется URL роута или набор параметров. И вот, спустя несколько часов отладки, вы понимаете, что ваш фронтенд отправляет запросы в никуда или с неверными данными. Больно, обидно, досадно. А что, если бы ваш TypeScript-фронтенд всегда знал, какие роуты и методы доступны на бэкенде, да еще и с полной типовой безопасностью?

Именно эту проблему решает Laravel Wayfinder – свежий, но уже очень многообещающий проект от команды Laravel. Это не просто очередная утилита, а настоящий мост, который соединяет ваш Laravel-бэкенд и TypeScript-фронтенд, делая их единым, гармонично работающим целым. Забудьте о ручной синхронизации, хардкоде URL и головной боли из-за изменившихся параметров. Wayfinder делает это за вас, автоматически.

Что такое Laravel Wayfinder и зачем он нужен?

По сути, Laravel Wayfinder — это инструмент, который берёт ваши контроллеры и роуты Laravel, анализирует их и на основе этой информации генерирует полностью типизированные TypeScript-функции. Эти функции вы можете импортировать и использовать в своём клиентском коде так же, как любые другие TypeScript-функции. Это значит, что вы можете вызывать бэкенд-эндпоинты прямо из фронтенда, не беспокоясь о правильности URL, HTTP-методе или наборе параметров.

Кому это будет полезно? Любому разработчику, который строит современные одностраничные приложения (SPA) или гибридные проекты, где Laravel выступает в роли API, а фронтенд написан на React, Vue, Angular или Svelte с использованием TypeScript. Если вы цените типовую безопасность, скорость разработки и хотите минимизировать ошибки, связанные с взаимодействием между фронтендом и бэкендом, Wayfinder — ваш выбор.

Ключевые возможности: как Wayfinder меняет игру

Давайте разберем, что именно делает Wayfinder таким удобным и мощным инструментом.

1. Автоматическая генерация типобезопасных функций

Это сердце Wayfinder. Вместо того, чтобы вручную писать интерфейсы или типы для каждого эндпоинта, Wayfinder делает это за вас. Он анализирует ваши контроллеры и роуты, а затем создает соответствующие TypeScript-файлы. Например, если у вас есть контроллер PostController с методом show(Post $post), Wayfinder сгенерирует функцию, которая ожидает ID поста и возвращает объект с URL и методом.

import { show } from "@/actions/App/Http/Controllers/PostController";

show(1); // { url: "/posts/1", method: "get" }

Или, если вам нужен только URL:

import { show } from "@/actions/App/Http/Controllers/PostController";

show.url(1); // "/posts/1"

2. Гибкая работа с параметрами роутов

Wayfinder умеет обрабатывать различные формы передачи параметров, что делает его очень удобным. Вы можете передавать их как отдельные аргументы, объекты или даже вложенные объекты, если в роуте используется привязка модели по ключу (например, {post:slug}).

import { show, update } from "@/actions/App/Http/Controllers/PostController";

// Одиночный параметр
show(1);
show({ id: 1 });

// Несколько параметров
update([1, 2]);
update({ post: 1, author: 2 });
update({ post: { id: 1 }, author: { id: 2 } });

// Если роут /posts/{post:slug}
show("my-new-post");
show({ slug: "my-new-post" });

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

3. Поддержка именованных роутов и инвокабельных контроллеров

Wayfinder не ограничивается только методами контроллеров. Он также умеет генерировать функции для именованных роутов, что очень удобно, если вы активно используете route()-хелпер в Laravel.

import { show } from "@/routes/post";

// Если именованный роут `post.show`
show(1); // { url: "/posts/1", method: "get" }

А если у вас есть инвокабельные контроллеры (те, что используют метод __invoke), Wayfinder тоже их поддерживает:

import StorePostController from "@/actions/App/Http/Controllers/StorePostController";

StorePostController();

4. Упрощенные HTML-формы

Даже если вы используете традиционные HTML-формы, Wayfinder может значительно упростить их создание. Активировав опцию --with-form при генерации, вы получите специальный вариант .form(), который автоматически сгенерирует атрибуты action и method для вашего тега <form>.

import { store, update } from "@/actions/App/Http/Controllers/PostController";

const Page = () => (
    <form {...store.form()}>
        {/* <form action="/posts" method="post"> */}
        {/* ... */}
    </form>
);

const Page = () => (
    <form {...update.form(1)}>
        {/* <form action="/posts/1?_method=PATCH" method="post"> */}
        {/* ... */}
    </form>
);

Это избавляет от ручного формирования URL и скрытых полей для HTTP-методов, отличных от GET и POST.

5. Управление Query-параметрами

Вам нужно добавить параметры запроса к URL? Wayfinder предоставляет удобный options объект с полем query или mergeQuery.

import { show } from "@/actions/App/Http/Controllers/PostController";

const options = {
    query: {
        page: 1,
        sort_by: "name",
    },
};

show(1, options); // { url: "/posts/1?page=1&sort_by=name", method: "get" }

А mergeQuery позволяет объединять параметры с уже существующими в URL, что очень удобно для пагинации или фильтрации.

6. Бесшовная интеграция с Inertia.js

Для тех, кто работает с Inertia.js, Wayfinder — это просто находка. Результаты функций Wayfinder можно напрямую передавать в useForm().submit() или в href компонента Link.

import { useForm } from "@inertiajs/react";
import { store } from "@/actions/App/Http/Controllers/PostController";

const form = useForm({
    name: "My Big Post",
});

form.submit(store()); // Отправит POST запрос на `/posts`

import { Link } from "@inertiajs/react";
import { show } from "@/actions/App/Http/Controllers/PostController";

const Nav = () => <Link href={show(1)}>Показать первый пост</Link>;

Это максимально упрощает взаимодействие с бэкендом в Inertia-приложениях, делая код чище и надежнее.

Как это работает под капотом?

Laravel Wayfinder состоит из двух основных частей:

1. Composer-пакет для Laravel: Он содержит логику для анализа ваших роутов и контроллеров, а также команду php artisan wayfinder:generate, которая выполняет основную работу по генерации TypeScript-файлов. Эти файлы по умолчанию сохраняются в resources/js/wayfinder, resources/js/actions и resources/js/routes.
2. Vite-плагин @laravel/vite-plugin-wayfinder: Этот плагин гарантирует, что ваши роуты будут автоматически перегенерироваться во время сборки Vite и при каждом изменении файлов во время работы dev-сервера. Это критически важно для поддержания актуальности типов.

Сгенерированные файлы можно смело добавлять в .gitignore, так как они полностью пересоздаются при каждой сборке или запуске команды генерации.

Практическое применение: меньше ошибок, больше скорости

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

• Снижение количества ошибок: Благодаря типовой безопасности, большинство проблем с эндпоинтами будут обнаружены еще на этапе компиляции TypeScript, а не в рантайме.
• Ускорение разработки: Вам больше не нужно постоянно переключаться между бэкендом и фронтендом, чтобы проверить названия роутов или параметры. Всё доступно прямо в вашем IDE с автодополнением.
• Улучшение поддерживаемости кода: Код становится более читаемым и понятным, так как вы видите, какие данные ожидаются для каждого вызова API.
• Облегчение онбординга: Новым членам команды будет гораздо проще разобраться, как взаимодействовать с API, благодаря четко определенным типам.

Выводы: стоит ли пробовать?

Безусловно! Laravel Wayfinder — это глоток свежего воздуха для всех, кто строит приложения на Laravel и TypeScript. Он значительно упрощает и улучшает процесс взаимодействия между двумя частями вашего приложения. Несмотря на то, что проект находится в стадии Beta, и API может меняться (как предупреждают сами разработчики), его потенциал очевиден. Учитывая, что это официальный пакет от команды Laravel, можно ожидать его активного развития и стабильности в будущем.

Кому особенно подойдет?

• Разработчикам, использующим Laravel и TypeScript (очевидно).
• Тем, кто работает с Vite для сборки фронтенда.
• Проектам, активно использующим Inertia.js, где Wayfinder раскрывается по-настоящему.
• Командам, стремящимся к повышению качества кода и снижению количества багов.

Я настоятельно рекомендую попробовать Laravel Wayfinder в вашем следующем или текущем проекте. Он может стать тем самым инструментом, который сделает вашу разработку более приятной, эффективной и, что самое главное, менее подверженной ошибкам. Позвольте вашему бэкенду и фронтенду наконец-то заговорить на одном, понятном всем языке!