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 不仅限于控制器方法。它还可以为命名路由生成函数，如果你积极使用 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>
);

这消除了手动构建 URL 和为 GET 和 POST 以外的 HTTP 方法添加隐藏字段的需要。

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() 或 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. 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 构建应用程序的人带来了一股新鲜空气。它显著简化和改善了应用程序两部分之间的交互过程。尽管该项目处于 Beta 阶段，API 可能会发生变化（正如开发者自己警告的那样），但其潜力是显而易见的。考虑到这是 Laravel 团队的官方包，我们可以期待积极的开发和未来的稳定性。

它特别适合谁？

• 使用 Laravel 和 TypeScript 的开发者（显而易见）。
• 使用 Vite 进行前端构建的人。
• 积极使用 Inertia.js 的项目，Wayfinder 在这里真正大放异彩。
• 追求更高代码质量和更少 bug 的团队。

我强烈建议在你下一个或当前项目中尝试 Laravel Wayfinder。它可以成为那个让你的开发更愉快、更高效、更重要的是更不易出错的工具。让你的后端和前端终于使用同一种通用语言！