Laravel Wayfinder：バックエンドとフロントエンドが同じ言語を話すとき

このような経験はありませんか？TypeScriptでフロントエンドを楽しく書いているのに、Laravelバックエンドの奥底でルートURLやパラメータのセットが変更されてしまう。そして、何時間もデバッグを繰り返した後、フロントエンドがどこにも送信されていない，或者は正しくないデータを送信していることに気づく。これは痛苦で、フラストレーションが溜まり、面倒です。もし、あなたのTypeScriptフロントエンドが、バックエンドでどのルートとメソッドが利用可能かを、完全に型安全でありながら常に知っていたとしたらどうでしょうか？

これがLaravel Wayfinderがまさに解決する問題です—Laravelチームによる新鮮ですがすでに非常に有望なプロジェクトです。これは単なるユーティリティではなく、LaravelバックエンドとTypeScriptフロントエンドを接続し、それらを単一の調和のとれた動作する全体にする真の橋渡し役です。手動の同期、ハードコードされたURL、パラメータ変更による頭痛とはお別れです。Wayfinderがこれを自動的に行ってくれます。

Laravel Wayfinderとは？なぜ必要なのか？

本質的に、Laravel WayfinderはLaravelのコントローラーとルートを取得し、分析し、この情報に基づいて完全に型付けされたTypeScript関数を生成するツールです。これらの関数は、他のTypeScript関数と同じようにインポートしてクライアントコードで使用できます。つまり、URLの正確さ、HTTPメソッド、パラメータのセットを心配することなく、フロントエンドからバックエンドエンドポイントを直接呼び出すことができます。

誰が恩恵を受けるのか？LaravelをAPIとして提供し、フロントエンドをReact、Vue、Angular、またはSvelteでTypeScriptを使用して書く、モダンなシングルページアプリケーション（SPA）またはハイブリッドプロジェクトを構築するすべての開発者です。型安全性、開発速度を重視し、フロントエンドとバックエンドの相互作用に関連するエラーを最小限に抑えたいなら、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はコントラーメソッドだけに限定されません。名前付きルート用の関数も生成でき、Laravelでroute()ヘルパーを積極的に使用している場合に非常に便利です。

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>
);

これにより、GETとGET以外のHTTPメソッドのURLと隠しフィールドを手動で形成する必要がなくなります。

5. クエリパラメータの管理

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()またはLinkコンポーネントのhrefに渡すことができます。

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は2つの主要部分で構成されています：

1. Laravel用のComposerパッケージ：ルートとコントローラーを分析するロジックと、TypeScriptファイルの生成という主要な作業を行うphp artisan wayfinder:generateコマンドが含まれています。これらのファイルはデフォルトでresources/js/wayfinder、resources/js/actions、resources/js/routesに保存されます。
2. Viteプラグイン@laravel/vite-plugin-wayfinder：このプラグインは、Viteビルド時および開発サーバー動作中のファイル変更時にルートが自動的に再生成されることを保証します。これは型を最新の状態に保つために非常に重要です。

生成されたファイルは安全に.gitignoreに追加できます。各ビルドまたは生成コマンド実行時に完全に再作成されるためです。

実践的な応用：エラーが減り、速度が上がる

私の実践では、フロントエンドとバックエンドの統合が多くのエラーの原因になっていることに頻繁に遭遇します。URLの書き間違い、忘れられたパラメータ、変更されたルート名がフロントエンドで同期されなかった...Wayfinderはこれらの問題を根本から解決します。開発プロセスに確信と予測可能性をもたらします：

• エラー数の削減：型安全性によりほとんどのエンドポイントの問題は実行時ではなく、TypeScriptコンパイル段階で検出されます。
• 開発速度の向上：ルート名やパラメータを確認するためにバックエンドとフロントエンドの間で常に切り替える必要がなくなります。すべてがオートコンプリート付きのIDEで바로利用可能です。
• コードの保守性の向上：コードがより読みやすく理解しやすくなります。各API呼び出しにどのようなデータが期待されているかを確認できるためです。
• オンボーディングが容易に：明確に定義された型 덕분에、新しいチームメンバーがAPIとの相互作用の方法を理解するのがはるかに簡単になります。

結論：試す価値はあるか？

ぜひ試してください！Laravel Wayfinderは、LaravelとTypeScriptでアプリケーションを構築するすべての人にとって新鮮な風です。アプリケーションの2つの部分の相互作用プロセスを大幅に簡略化、改善します。プロジェクトはベータ段階でAPIが変更される可能性がある（開発者自身が警告している通り）ものの、その潜在力は明らかです。Laravelチームの公式パッケージであることを考えると、今後も積極的に開発され安定することが期待できます。

誰が特におすすめか？

• LaravelとTypeScriptを使用している開発者（ очевидно）。
• フロントエンドビルドにViteを使用している人。
• Inertia.jsを активно 使用しているプロジェクトでは、Wayfinderが真に輝く。
• より高いコード品質と少ないバグを追求するチーム。

次のプロジェクトまたは現在のプロジェクトでLaravel Wayfinderを試すことを強くおすすめします。これは開発をより楽しく、効率的に、そして何よりエラーが発生しにくくするツールになるでしょう。バックエンドとフロントエンドがついに同じ、普遍的に理解される言語を話すようにしましょう！