Laravel Wayfinder: Gdy backend i frontend mówią tym samym językiem

Znasz to uczucie? Piszesz sobie spokojnie frontend w TypeScripcie, ale gdzieś w głębi Twojego Laravela backend zmienia się adres URL trasy lub zestaw parametrów. A potem, po godzinach debugowania, orientujesz się, że Twój frontend wysyła żądania w nicość lub z nieprawidłowymi danymi. To boli, jest frustrujące i irytujące. Co jeśli Twój frontend w TypeScripcie zawsze wiedziałby, które trasy i metody są dostępne w backendzie, wraz z pełnym bezpieczeństwem typów?

To dokładnie problem, który rozwiązuje Laravel Wayfinder – świeży, ale już bardzo obiecujący projekt od zespołu Laravel. To nie jest kolejne narzędzie, ale prawdziwy most łączący Twój backend Laravel z frontendem TypeScript, sprawiając, że stanowią one jedną, harmonijnie działającą całość. Zapomnij o ręcznej synchronizacji, zakodowanych na twardo URL-ach i bólach głowy od zmienionych parametrów. Wayfinder robi to za Ciebie, automatycznie.

Czym jest Laravel Wayfinder i dlaczego go potrzebujesz?

Essencji Laravel Wayfinder to narzędzie, które pobiera Twoje kontrolery i trasy Laravel, analizuje je, a na podstawie tej informacji generuje w pełni typowane funkcje TypeScript. Te funkcje można importować i używać w kodzie klienckim tak samo jak każde inne funkcje TypeScript. Oznacza to, że możesz wywoływać endpointy backendu bezpośrednio z frontendu, nie martwiąc się o poprawność URL, metody HTTP czy zestawu parametrów.

Kto skorzysta? Każdy deweloper budujący nowoczesne aplikacje jednostronicowe (SPA) lub projekty hybrydowe, gdzie Laravel służy jako API, a frontend jest napisany w React, Vue, Angular lub Svelte z użyciem TypeScript. Jeśli cenisz bezpieczeństwo typów, szybkość developmentu i chcesz zminimalizować błędy związane z interakcją frontend-backend, Wayfinder jest dla Ciebie.

Kluczowe funkcje: jak Wayfinder zmienia zasady gry

Przyjrzyjmy się, co sprawia, że Wayfinder jest tak wygodnym i potężnym narzędziem.

1. Automatyczna generacja funkcji z bezpieczeństwem typów

To serce Wayfindera. Zamiast ręcznie pisać interfejsy lub typy dla każdego endpointa, Wayfinder robi to za Ciebie. Analizuje Twoje kontrolery i trasy, a następnie tworzy odpowiednie pliki TypeScript. Na przykład, jeśli masz kontroler PostController z metodą show(Post $post), Wayfinder wygeneruje funkcję, która oczekuje ID posta i zwraca obiekt z URL i metodą.

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

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

Albo, jeśli potrzebujesz tylko URL:

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

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

2. Elastyczna obsługa parametrów tras

Wayfinder potrafi obsłużyć różne formy przekazywania parametrów, co jest bardzo wygodne. Możesz przekazywać je jako osobne argumenty, obiekty, a nawet zagnieżdżone obiekty, jeśli trasa używa model bindingu po kluczu (na przykład {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" });

To pozwala pisać czystszy i bardziej intuicyjny kod frontendu, nie myśląc o tym, jak Laravel oczekuje parametrów w backendzie.

3. Wsparcie dla nazwanych tras i kontrolerów invokable

Wayfinder nie ogranicza się tylko do metod kontrolerów. Potrafi też generować funkcje dla nazwanych tras, co jest bardzo wygodne, jeśli aktywnie używasz helpera route() w Laravelu.

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

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

A jeśli masz kontrolery invokable (te używające metody __invoke), Wayfinder też je wspiera:

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

StorePostController();

4. Uproszczone formularze HTML

Nawet jeśli używasz tradycyjnych formularzy HTML, Wayfinder może znacząco uprościć ich tworzenie. Włączając opcję --with-form podczas generacji, otrzymasz specjalny wariant .form(), który automatycznie generuje atrybuty action i method dla Twojego tagu <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>
);

Eliminuje to potrzebę ręcznego tworzenia URL-i i ukrytych pól dla metod HTTP innych niż GET i POST.

5. Zarządzanie parametrami query

Potrzebujesz dodać parametry query do URL? Wayfinder udostępnia wygodny obiekt options z polem query lub 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" }

A mergeQuery pozwala łączyć parametry z tymi już znajdującymi się w URL, co jest bardzo wygodne przy paginacji lub filtrowaniu.

6. Bezproblemowa integracja z Inertia.js

Dla tych, którzy pracują z Inertia.js, Wayfinder to prawdziwe znalezisko. Wyniki funkcji Wayfinder można przekazywać bezpośrednio do useForm().submit() lub do href komponentu 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>;

To maksymalnie upraszcza interakcję z backendem w aplikacjach Inertia, sprawiając, że kod jest czystszy i bardziej niezawodny.

Jak to działa pod maską

Laravel Wayfinder składa się z dwóch głównych części:

1. Pakiet Composer dla Laravel: Zawiera logikę analizującą Twoje trasy i kontrolery, a także polecenie php artisan wayfinder:generate, które wykonuje główną pracę generowania plików TypeScript. Pliki te są domyślnie zapisywane do resources/js/wayfinder, resources/js/actions i resources/js/routes.
2. Wtyczka Vite @laravel/vite-plugin-wayfinder: Ta wtyczka zapewnia automatyczną regenerację tras podczas budowania Vite i przy każdej zmianie plików podczas działania serwera deweloperskiego. To krytycznie ważne dla utrzymania typów aktualnych.

Wygenerowane pliki można bezpiecznie dodać do .gitignore, ponieważ są w pełni odtwarzane przy każdym budowaniu lub uruchomieniu polecenia generacji.

Praktyczne zastosowanie: mniej błędów, więcej szybkości

W mojej praktyce często spotykam się z tym, że integracja frontend-backend jest źródłem wielu błędów. Nieprawidłowo napisany URL, zapomniany parametr, zmieniona nazwa trasy, która nie została zsynchronizowana po stronie frontendu... Wayfinder rozwiązuje te problemy u źródła. Wprowadza pewność i przewidywalność do procesu developmentu:

• Zmniejszona liczba błędów: Dzięki bezpieczeństwu typów, większość problemów z endpointami zostanie wykryta na etapie kompilacji TypeScript, a nie w runtime.
• Szybszy development: Nie musisz już ciągle przełączać się między backendem a frontendem, żeby sprawdzać nazwy tras czy parametry. Wszystko jest dostępne od razu w Twoim IDE z autouzupełnianiem.
• Poprawiona utrzymywalność kodu: Kod staje się bardziej czytelny i zrozumiały, ponieważ widać, jakie dane są oczekiwane dla każdego wywołania API.
• Łatwiejsze wdrożenie nowych osób: Nowi członkowie zespołu znacznie łatwiej zrozumieją, jak komunikować się z API, dzięki jasno zdefiniowanym typom.

Podsumowanie: czy warto wypróbować?

Zdecydowanie tak! Laravel Wayfinder to powiew świeżości dla wszystkich budujących aplikacje z Laravelem i TypeScriptem. Znacząco upraszcza i usprawnia proces interakcji między dwiema częściami Twojej aplikacji. Chociaż projekt jest w fazie Beta i API może się zmienić (jak ostrzegają sami deweloperzy), jego potencjał jest oczywisty. Biorąc pod uwagę, że jest to oficjalny pakiet od zespołu Laravel, możemy spodziewać się aktywnego rozwoju i stabilności w przyszłości.

Dla kogo jest szczególnie odpowiedni?

• Deweloperzy używający Laravel i TypeScript (oczywiście).
• Ci, którzy pracują z Vite do budowania frontendu.
• Projekty aktywnie używające Inertia.js, gdzie Wayfinder naprawdę błyszczy.
• Zespoły dążące do wyższej jakości kodu i mniejszej liczby błędów.

Polecam wypróbować Laravel Wayfinder w Twoim następnym lub obecnym projekcie. Może stać się tym właśnie narzędziem, które sprawi, że Twój development będzie przyjemniejszy, wydajniejszy i, co najważniejsze, mniej podatny na błędy. Niech Twój backend i frontend wreszcie mówią tym samym, uniwersalnie zrozumiałym językiem!