# 路由

-   [基础路由](#basic-routing)
    -   [默认路由文件](#the-default-route-files)
    -   [重定向路由](#redirect-routes)
    -   [视图路由](#view-routes)
    -   [列出你的路由](#listing-your-routes)
    -   [路由自定义](#routing-customization)
-   [路由参数](#route-parameters)
    -   [必填参数](#required-parameters)
    -   [可选参数](#parameters-optional-parameters)
    -   [正则表达式约束](#parameters-regular-expression-constraints)
-   [命名路由](#named-routes)
-   [路由组](#route-groups)
    -   [中间件](#route-group-middleware)
    -   [控制器](#route-group-controllers)
    -   [子域名路由](#route-group-subdomain-routing)
    -   [路由前缀](#route-group-prefixes)
    -   [路由名称前缀](#route-group-name-prefixes)
-   [路由模型绑定](#route-model-binding)
    -   [隐式绑定](#implicit-binding)
    -   [隐式枚举绑定](#implicit-enum-binding)
    -   [显式绑定](#explicit-binding)
-   [兜底路由](#fallback-routes)
-   [速率限制](#rate-limiting)
    -   [定义速率限制器](#defining-rate-limiters)
    -   [将速率限制器附加到路由](#attaching-rate-limiters-to-routes)
-   [表单方法伪造](#form-method-spoofing)
-   [访问当前路由](#accessing-the-current-route)
-   [跨源资源共享（CORS）](#cors)
-   [路由缓存](#route-caching)

## 基础路由

```php
use Illuminate\Support\Facades\Route;

Route::get('/greeting', function () {
    return 'Hello World';
});
```

### 默认路由文件

所有 Laravel 路由都定义在你的路由文件中，这些文件位于 `routes` 目录下。Laravel 会根据你的应用程序 `bootstrap/app.php` 文件中指定的配置自动加载这些文件。`routes/web.php` 文件定义用于你的 Web 界面的路由。这些路由会被分配到 `web` [中间件组](/docs/laravel/13.x/middleware#laravels-default-middleware-groups)，该中间件组提供诸如会话状态和 CSRF 保护等功能。



对于大多数应用程序，你将首先在 `routes/web.php` 文件中定义路由。在 `routes/web.php` 中定义的路由可以通过在浏览器中输入定义的路由的 URL 来访问。例如，你可以通过在浏览器中导航到 `http://example.com/user` 来访问以下路由：

```php
use App\Http\Controllers\UserController;

Route::get('/user', [UserController::class, 'index']);
```

<a name="api-routes"></a>
#### API Routes

如果你的应用程序还将提供无状态 API，你可以使用 `install:api` Artisan 命令启用 API 路由：

```shell
php artisan install:api
```

`install:api` 命令安装了 [Laravel Sanctum](/docs/laravel/13.x/sanctum)，它提供了一个强大而简单的 API 令牌认证守卫，可用于对第三方 API 使用者、SPAs 或移动应用程序进行身份验证。此外，`install:api` 命令创建了 `routes/api.php` 文件:

```php
Route::get('/user', function (Request $request) {
    return $request->user();
})->middleware('auth:sanctum');
```

当然，对于应公开访问的路由，你可以自由省略 `auth:sanctum` 中间件。

`routes/api.php` 中的路由是无状态的，并分配给 `api`  [中间件组](/docs/laravel/13.x/middleware#laravels-default-middleware-groups)。此外，`/api` URI 前缀会自动应用于这些路由，因此你无需手动将其应用于文件中的每个路由。你可以通过修改应用程序的 `bootstrap/app.php` 文件来更改前缀：



```php
->withRouting(
    api: __DIR__.'/../routes/api.php',
    apiPrefix: 'api/admin',
    // ...
)
```

<a name="available-router-methods"></a>
#### 可用的路由器方法



路由允许你注册响应任何 HTTP 请求的路由：

```php
Route::get($uri, $callback);
Route::post($uri, $callback);
Route::put($uri, $callback);
Route::patch($uri, $callback);
Route::delete($uri, $callback);
Route::options($uri, $callback);
```


有时你可能需要注册一个响应多个 HTTP 动词的路由。你可以使用 `match`  方法来实现。或者你可以使用 `any` 方法注册一个响应所有 HTTP 动词的路由：

```php
Route::match(['get', 'post'], '/', function () {
    // ...
});

Route::any('/', function () {
    // ...
});
```

> [!注意]
> 在定义共享相同 URI 配置项的多个路由时，必须优先定义使用 `get`, `post`, `put`, `patch`, `delete` 和  `options` 方法的路由， 然后再定义使用 `any`, `match` 和  `redirect` 方法。这能确保传入请求被匹配到正确路由。

<a name="dependency-injection"></a>
#### 依赖注入

你可以在路由回调函数的签名中为所需的依赖项添加类型提示。 Laravel  [服务容器](/docs/laravel/13.x/container) 会自动解析并注入这些声明的依赖项到回调函数中。例如，你.可以引用  `Illuminate\Http\Request` 类，这样当前的 HTTP 请求就会自动注入到你的路由回调函数中

```php
use Illuminate\Http\Request;

Route::get('/users', function (Request $request) {
    // ...
});
```

<a name="csrf-protection"></a>
#### CSRF 防护

请注意，任何指向 `web` 路由文件中定义的 `POST`, `PUT`, `PATCH` 或 `DELETE`路由的 HTML 表单都应包含 CSRF 令牌字段。否则，请求将被拒绝。你可以在 [CSRF 文档](/docs/laravel/12.x/csrf) 中了解更多关于 CSRF 保护的信息：

```blade
<form method="POST" action="/profile">
    @csrf
    ...
</form>
```



### 重定向路由

如果你正在定义一个重定向到另一个 URI 的路由，可以使用 `Route::redirect` 方法。该方法提供了一个方便的快捷方式，这样你就不必为了执行一个简单的重定向而定义完整的路由或控制器：

```php
Route::redirect('/here', '/there');
```

默认情况下，`Route::redirect` 返回 `302` 状态码。你可以使用可选的第三个参数来自定义状态码：

```php
Route::redirect('/here', '/there', 301);
```

或者，你可以使用 `Route::permanentRedirect` 方法返回 `301` 状态码：

```php
Route::permanentRedirect('/here', '/there');
```

> [!警告]
> 在重定向路由中使用路由参数时，以下参数由 Laravel 保留，不能使用：`destination` 和 `status`。

### 视图路由

如果你的路由只需要返回一个[视图](/docs/laravel/13.x/views)，可以使用 `Route::view` 方法。与 `redirect` 方法一样，该方法提供了一个简单的快捷方式，这样你就不必定义完整的路由或控制器。`view` 方法接受一个 URI 作为第一个参数，视图名称作为第二个参数。此外，你还可以提供一个数据数组作为可选的第三个参数，用于传递给视图：

```php
Route::view('/welcome', 'welcome');

Route::view('/welcome', 'welcome', ['name' => 'Taylor']);
```

> [!警告]
> 在视图路由中使用路由参数时，以下参数由 Laravel 保留，不能使用：`view`、`data`、`status` 和 `headers`。

### 列出你的路由



`route:list` Artisan 命令可以轻松提供你的应用程序所定义的所有路由的概览：

```shell
php artisan route:list
```

默认情况下，分配给每个路由的路由中间件不会显示在 `route:list` 输出中；不过，你可以通过在命令中添加 `-v` 选项，指示 Laravel 显示路由中间件和中间件组名称：

```shell
php artisan route:list -v

# 展开中间件组...
php artisan route:list -vv
```

你还可以指示 Laravel 只显示以给定 URI 开头的路由：

```shell
php artisan route:list --path=api
```

此外，在执行 `route:list` 命令时，你可以通过提供 `--except-vendor` 选项，指示 Laravel 隐藏任何由第三方包定义的路由：

```shell
php artisan route:list --except-vendor
```

同样，在执行 `route:list` 命令时，你也可以通过提供 `--only-vendor` 选项，指示 Laravel 只显示由第三方包定义的路由：

```shell
php artisan route:list --only-vendor
```

### 路由自定义

默认情况下，你的应用程序路由由 `bootstrap/app.php` 文件进行配置和加载：

```php
<?php

use Illuminate\Foundation\Application;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )->create();
```

然而，有时你可能想要定义一个全新的文件来包含应用程序路由的一个子集。要实现这一点，你可以向 `withRouting` 方法提供一个 `then` 闭包。在这个闭包中，你可以注册应用程序所需的任何其他路由：

```php
use Illuminate\Support\Facades\Route;

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
    then: function () {
        Route::middleware('api')
            ->prefix('webhooks')
            ->name('webhooks.')
            ->group(base_path('routes/webhooks.php'));
    },
)
```



或者，你甚至可以通过向 `withRouting` 方法提供一个 `using` 闭包来完全控制路由注册。当传入此参数时，框架将不会注册任何 HTTP 路由，你需要负责手动注册所有路由：

```php
use Illuminate\Support\Facades\Route;

->withRouting(
    commands: __DIR__.'/../routes/console.php',
    using: function () {
        Route::middleware('api')
            ->prefix('api')
            ->group(base_path('routes/api.php'));

        Route::middleware('web')
            ->group(base_path('routes/web.php'));
    },
)
```

## 路由参数

### 必填参数

有时你需要在路由中捕获 URI 的片段。例如，你可能需要从 URL 中捕获用户的 ID。你可以通过定义路由参数来实现：

```php
Route::get('/user/{id}', function (string $id) {
    return 'User '.$id;
});
```

你可以根据路由需要定义任意数量的路由参数：

```php
Route::get('/posts/{post}/comments/{comment}', function (string $postId, string $commentId) {
    // ...
});
```

路由参数始终包裹在 `{}` 大括号中，并且应由字母字符组成。路由参数名称中也可以使用下划线（`_`）。路由参数会根据它们的顺序被注入到路由回调 / 控制器中——路由回调 / 控制器参数的名称并不重要。

#### 参数和依赖注入

如果你的路由有一些依赖项，希望 Laravel 服务容器自动将它们注入到路由回调中，则应将路由参数列在依赖项之后：

```php
use Illuminate\Http\Request;

Route::get('/user/{id}', function (Request $request, string $id) {
    return 'User '.$id;
});
```



### 可选参数

有时你可能需要指定一个不一定总是出现在 URI 中的路由参数。你可以通过在参数名称后放置一个 `?` 标记来实现。请确保为该路由对应的变量提供一个默认值：

```php
Route::get('/user/{name?}', function (?string $name = null) {
    return $name;
});

Route::get('/user/{name?}', function (?string $name = 'John') {
    return $name;
});
```

### 正则表达式约束

你可以在路由实例上使用 `where` 方法来约束路由参数的格式。`where` 方法接受参数名称和一个正则表达式，该正则表达式用于定义应如何约束该参数：

```php
Route::get('/user/{name}', function (string $name) {
    // ...
})->where('name', '[A-Za-z]+');

Route::get('/user/{id}', function (string $id) {
    // ...
})->where('id', '[0-9]+');

Route::get('/user/{id}/{name}', function (string $id, string $name) {
    // ...
})->where(['id' => '[0-9]+', 'name' => '[a-z]+']);
```

为方便起见，一些常用的正则表达式模式提供了辅助方法，使你可以快速为路由添加模式约束：

```php
Route::get('/user/{id}/{name}', function (string $id, string $name) {
    // ...
})->whereNumber('id')->whereAlpha('name');

Route::get('/user/{name}', function (string $name) {
    // ...
})->whereAlphaNumeric('name');

Route::get('/user/{id}', function (string $id) {
    // ...
})->whereUuid('id');

Route::get('/user/{id}', function (string $id) {
    // ...
})->whereUlid('id');

Route::get('/category/{category}', function (string $category) {
    // ...
})->whereIn('category', ['movie', 'song', 'painting']);

Route::get('/category/{category}', function (string $category) {
    // ...
})->whereIn('category', CategoryEnum::cases());
```



如果传入的请求不匹配路由模式约束，将返回一个 404 HTTP 响应。

#### 全局约束

如果你希望某个路由参数始终受给定正则表达式的约束，可以使用 `pattern` 方法。你应该在应用程序的 `App\Providers\AppServiceProvider` 类的 `boot` 方法中定义这些模式：

```php
use Illuminate\Support\Facades\Route;

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Route::pattern('id', '[0-9]+');
}
```

一旦定义了该模式，它就会自动应用到所有使用该参数名称的路由：

```php
Route::get('/user/{id}', function (string $id) {
    // 仅当 {id} 为数字时才会执行...
});
```

#### 编码的正斜杠

Laravel 路由组件允许路由参数值中包含除 `/` 之外的所有字符。你必须使用 `where` 条件正则表达式显式允许 `/` 成为占位符的一部分：

```php
Route::get('/search/{search}', function (string $search) {
    return $search;
})->where('search', '.*');
```
> [!警告]
> 编码的正斜杠仅在最后一个路由段中受支持。

## 命名路由

命名路由允许你方便地为特定路由生成 URL 或重定向。你可以通过在路由定义后链式调用 `name` 方法来为路由指定名称：

```php
Route::get('/user/profile', function () {
    // ...
})->name('profile');
```

你也可以为控制器动作指定路由名称：

```php
Route::get(
    '/user/profile',
    [UserProfileController::class, 'show']
)->name('profile');
```

> [!警告]
> 路由名称应始终保持唯一。



#### 为命名路由生成 URL

一旦你为某个路由指定了名称，就可以在通过 Laravel 的 `route` 和 `redirect` 辅助函数生成 URL 或重定向时使用该路由名称：

```php
// 生成 URL...
$url = route('profile');

// 生成重定向...
return redirect()->route('profile');

return to_route('profile');
```

如果命名路由定义了参数，你可以将参数作为第二个参数传递给 `route` 函数。给定的参数会自动插入到生成的 URL 中正确的位置：

```php
Route::get('/user/{id}/profile', function (string $id) {
    // ...
})->name('profile');

$url = route('profile', ['id' => 1]);
```

如果你在数组中传递了额外的参数，这些键 / 值对会自动添加到生成 URL 的查询字符串中：

```php
Route::get('/user/{id}/profile', function (string $id) {
    // ...
})->name('profile');

$url = route('profile', ['id' => 1, 'photos' => 'yes']);

// http://example.com/user/1/profile?photos=yes
```

> [!注意]
> 有时，你可能希望为 URL 参数指定请求范围内的默认值，例如当前语言环境。要实现这一点，可以使用 [URL::defaults 方法](/docs/laravel/13.x/urls#default-values)。

#### 检查当前路由

如果你想判断当前请求是否被路由到某个给定的命名路由，可以在 Route 实例上使用 `named` 方法。例如，你可以从路由中间件中检查当前路由名称：

```php
use Closure;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

/**
 * 处理传入的请求。
 *
 * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
 */
public function handle(Request $request, Closure $next): Response
{
    if ($request->route()->named('profile')) {
        // ...
    }

    return $next($request);
}
```



## 路由组

路由组允许你在大量路由之间共享路由属性，例如中间件，而无需在每个单独的路由上定义这些属性。

嵌套路由组会尝试智能地与其父组“合并”属性。中间件和 `where` 条件会被合并，而名称和前缀会被追加。命名空间分隔符和 URI 前缀中的斜杠会在适当的位置自动添加。

### 中间件

要为组内的所有路由分配[中间件](/docs/laravel/13.x/middleware)，可以在定义组之前使用 `middleware` 方法。中间件会按照它们在数组中列出的顺序执行：

```php
Route::middleware(['first', 'second'])->group(function () {
    Route::get('/', function () {
        // 使用 first 和 second 中间件...
    });

    Route::get('/user/profile', function () {
        // 使用 first 和 second 中间件...
    });
});
```

### 控制器

如果一组路由都使用同一个[控制器](/docs/laravel/13.x/controllers)，你可以使用 `controller` 方法为组内所有路由定义通用控制器。然后，在定义路由时，你只需要提供它们所调用的控制器方法：

```php
use App\Http\Controllers\OrderController;

Route::controller(OrderController::class)->group(function () {
    Route::get('/orders/{id}', 'show');
    Route::post('/orders', 'store');
});
```

### 子域名路由

路由组也可以用于处理子域名路由。子域名可以像路由 URI 一样分配路由参数，从而允许你捕获子域名的一部分，以便在你的路由或控制器中使用。可以通过在定义组之前调用 `domain` 方法来指定子域名：

```php
Route::domain('{account}.example.com')->group(function () {
    Route::get('/user/{id}', function (string $account, string $id) {
        // ...
    });
});
```



### 路由前缀

`prefix` 方法可用于为组中的每个路由添加给定的 URI 前缀。例如，你可能想为组内所有路由 URI 添加 `admin` 前缀：

```php
Route::prefix('admin')->group(function () {
    Route::get('/users', function () {
        // Matches The "/admin/users" URL
    });
});
```

### 路由名称前缀

`name` 方法可用于为组中的每个路由名称添加给定字符串作为前缀。例如，你可能想为组内所有路由的名称添加 `admin` 前缀。给定字符串会按照指定的内容原样添加到路由名称前，因此我们需要确保在前缀中提供尾随的 `.` 字符：

```php
Route::name('admin.')->group(function () {
    Route::get('/users', function () {
        // Route assigned name "admin.users"...
    })->name('users');
});
```

## 路由模型绑定

当向路由或控制器动作注入模型 ID 时，你通常会查询数据库以检索与该 ID 对应的模型。Laravel 路由模型绑定提供了一种便捷方式，可以自动将模型实例直接注入到你的路由中。例如，你可以注入与给定 ID 匹配的整个 `User` 模型实例，而不是注入用户的 ID。

### 隐式绑定

Laravel 会自动解析在路由或控制器动作中定义的 Eloquent 模型，只要其类型提示变量名与路由片段名称匹配。例如：

```php
use App\Models\User;

Route::get('/users/{user}', function (User $user) {
    return $user->email;
});
```



由于 `$user` 变量被类型提示为 `App\Models\User` Eloquent 模型，并且变量名称与 `{user}` URI 片段相匹配，因此 Laravel 会自动注入与请求 URI 中对应值匹配的 ID 的模型实例。如果在数据库中找不到匹配的模型实例，将会自动生成 404 HTTP 响应。

当然，在使用控制器方法时，也可以进行隐式绑定。同样，请注意 `{user}` URI 片段与控制器中的 `$user` 变量相匹配，而该变量包含 `App\Models\User` 类型提示：

```php
use App\Http\Controllers\UserController;
use App\Models\User;

// 路由定义...
Route::get('/users/{user}', [UserController::class, 'show']);

// 控制器方法定义...
public function show(User $user)
{
    return view('user.profile', ['user' => $user]);
}
```

#### 软删除模型

通常，隐式模型绑定不会检索已被[软删除](/docs/laravel/13.x/eloquent#soft-deleting)的模型。但是，你可以通过在路由定义上链式调用 `withTrashed` 方法，指示隐式绑定检索这些模型：

```php
use App\Models\User;

Route::get('/users/{user}', function (User $user) {
    return $user->email;
})->withTrashed();
```

#### 自定义键

有时，你可能希望使用 `id` 以外的列来解析 Eloquent 模型。为此，你可以在路由参数定义中指定该列：

```php
use App\Models\Post;

Route::get('/posts/{post:slug}', function (Post $post) {
    return $post;
});
```

如果你希望在检索给定模型类时，模型绑定始终使用 `id` 以外的数据库列，则可以在 Eloquent 模型上重写 `getRouteKeyName` 方法：

```php
/**
 * Get the route key for the model.
 */
public function getRouteKeyName(): string
{
    return 'slug';
}
```



#### 自定义键和作用域限定

当在单个路由定义中隐式绑定多个 Eloquent 模型时，你可能希望对第二个 Eloquent 模型进行作用域限定，使其必须是前一个 Eloquent 模型的子级。例如，请看下面这个路由定义，它会根据特定用户的 slug 检索一篇博客文章：

```php
use App\Models\Post;
use App\Models\User;

Route::get('/users/{user}/posts/{post:slug}', function (User $user, Post $post) {
    return $post;
});
```

当使用自定义键的隐式绑定作为嵌套路由参数时，Laravel 会自动限定查询范围，通过父模型来检索嵌套模型，并使用约定来猜测父模型上的关系名称。在这个例子中，Laravel 会假定 `User` 模型有一个名为 `posts` 的关系，即路由参数名称的复数形式，该关系可用于检索 `Post` 模型。

如果你愿意，也可以指示 Laravel 即使在未提供自定义键的情况下，也对“子级”绑定进行作用域限定。为此，你可以在定义路由时调用 `scopeBindings` 方法：

```php
use App\Models\Post;
use App\Models\User;

Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
    return $post;
})->scopeBindings();
```

或者，你也可以指示整个路由定义组使用作用域绑定：

```php
Route::scopeBindings()->group(function () {
    Route::get('/users/{user}/posts/{post}', function (User $user, Post $post) {
        return $post;
    });
});
```

类似地，你也可以通过调用 `withoutScopedBindings` 方法，明确指示 Laravel 不要对绑定进行作用域限定：

```php
Route::get('/users/{user}/posts/{post:slug}', function (User $user, Post $post) {
    return $post;
})->withoutScopedBindings();
```



#### 自定义缺失模型的行为

通常，如果找不到隐式绑定的模型，将会生成 404 HTTP 响应。不过，你可以在定义路由时调用 `missing` 方法来自定义此行为。`missing` 方法接收一个闭包，当无法找到隐式绑定的模型时，该闭包将会被调用：

```php
use App\Http\Controllers\LocationsController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redirect;

Route::get('/locations/{location:slug}', [LocationsController::class, 'show'])
    ->name('locations.view')
    ->missing(function (Request $request) {
        return Redirect::route('locations.index');
    });
```

### 隐式枚举绑定

PHP 8.1 引入了对 [Enums](https://www.php.net/manual/en/language.enumerations.backed.php) 的支持。为了配合这一特性，Laravel 允许你在路由定义中对[字符串支持的 Enum](https://www.php.net/manual/en/language.enumerations.backed.php) 进行类型提示，并且 Laravel 只有在该路由片段对应有效的 Enum 值时才会调用该路由。否则，将自动返回 404 HTTP 响应。例如，给定以下 Enum：

```php
<?php

namespace App\Enums;

enum Category: string
{
    case Fruits = 'fruits';
    case People = 'people';
}
```

你可以定义一个路由，只有当 `{category}` 路由片段为 `fruits` 或 `people` 时才会被调用。否则，Laravel 将返回 404 HTTP 响应：

```php
use App\Enums\Category;
use Illuminate\Support\Facades\Route;

Route::get('/categories/{category}', function (Category $category) {
    return $category->value;
});
```

### 显式绑定

为了使用模型绑定，你并不一定要使用 Laravel 基于隐式约定的模型解析。你也可以显式定义路由参数如何对应模型。要注册显式绑定，请使用路由器的 `model` 方法为给定参数指定类。你应该在 `AppServiceProvider` 类的 `boot` 方法开头定义你的显式模型绑定：

```php
use App\Models\User;
use Illuminate\Support\Facades\Route;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Route::model('user', User::class);
}
```



接下来，定义一个包含 `{user}` 参数的路由：

```php
use App\Models\User;

Route::get('/users/{user}', function (User $user) {
    // ...
});
```

由于我们已经将所有 `{user}` 参数绑定到 `App\Models\User` 模型，因此该类的实例将被注入到路由中。因此，例如，对 `users/1` 的请求将会从数据库中注入 ID 为 `1` 的 `User` 实例。

如果在数据库中找不到匹配的模型实例，将会自动生成 404 HTTP 响应。

#### 自定义解析逻辑

如果你希望定义自己的模型绑定解析逻辑，可以使用 `Route::bind` 方法。你传递给 `bind` 方法的闭包将接收 URI 片段的值，并应返回应该被注入到路由中的类实例。同样，此自定义操作应该在你的应用程序 `AppServiceProvider` 的 `boot` 方法中进行：

```php
use App\Models\User;
use Illuminate\Support\Facades\Route;

/**
 * 引导任何应用服务。
 */
public function boot(): void
{
    Route::bind('user', function (string $value) {
        return User::where('name', $value)->firstOrFail();
    });
}
```

或者，你可以在 Eloquent 模型上重写 `resolveRouteBinding` 方法。该方法将接收 URI 片段的值，并应返回应该被注入到路由中的类实例：

```php
/**
 * 检索绑定值对应的模型。
 *
 * @param  mixed  $value
 * @param  string|null  $field
 * @return \Illuminate\Database\Eloquent\Model|null
 */
public function resolveRouteBinding($value, $field = null)
{
    return $this->where('name', $value)->firstOrFail();
}
```



如果路由正在使用[隐式绑定作用域限定](#implicit-model-binding-scoping)，则会使用 `resolveChildRouteBinding` 方法来解析父模型的子绑定：

```php
/**
 * 检索绑定值对应的子模型。
 *
 * @param  string  $childType
 * @param  mixed  $value
 * @param  string|null  $field
 * @return \Illuminate\Database\Eloquent\Model|null
 */
public function resolveChildRouteBinding($childType, $value, $field)
{
    return parent::resolveChildRouteBinding($childType, $value, $field);
}
```

## 兜底路由

使用 `Route::fallback` 方法，你可以定义一个路由，当没有其他路由匹配传入请求时，该路由将会被执行。通常，未处理的请求会通过你的应用程序异常处理器自动渲染一个 “404” 页面。不过，由于你通常会在 `routes/web.php` 文件中定义 `fallback` 路由，因此 `web` 中间件组中的所有中间件都会应用到该路由。你可以根据需要自由地向该路由添加额外的中间件：

```php
Route::fallback(function () {
    // ...
});
```

## 速率限制

### 定义速率限制器

Laravel 包含强大且可自定义的速率限制服务，你可以使用它们来限制给定路由或路由组的流量。首先，你应该定义符合应用程序需求的速率限制器配置。

速率限制器可以在你的应用程序 `App\Providers\AppServiceProvider` 类的 `boot` 方法中定义：

```php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    RateLimiter::for('api', function (Request $request) {
        return Limit::perMinute(60)->by($request->user()?->id ?: $request->ip());
    });
}
```



速率限制器使用 `RateLimiter` 门面的 `for` 方法定义。`for` 方法接收一个速率限制器名称和一个闭包，该闭包返回应该应用于分配给该速率限制器的路由的限制配置。限制配置是 `Illuminate\Cache\RateLimiting\Limit` 类的实例。该类包含一些有用的“构建器”方法，因此你可以快速定义限制。速率限制器名称可以是你想要的任意字符串：

```php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;

/**
 * 引导任何应用服务。
 */
public function boot(): void
{
    RateLimiter::for('global', function (Request $request) {
        return Limit::perMinute(1000);
    });
}
```

如果传入请求超过指定的速率限制，Laravel 将自动返回一个带有 429 HTTP 状态码的响应。如果你希望定义自己的响应，并在触发速率限制时返回该响应，可以使用 `response` 方法：

```php
RateLimiter::for('global', function (Request $request) {
    return Limit::perMinute(1000)->response(function (Request $request, array $headers) {
        return response('Custom response...', 429, $headers);
    });
});
```

由于速率限制器回调会接收传入的 HTTP 请求实例，因此你可以根据传入请求或已认证用户动态构建合适的速率限制：

```php
RateLimiter::for('uploads', function (Request $request) {
    return $request->user()?->vipCustomer()
        ? Limit::none()
        : Limit::perHour(10);
});
```

#### 速率限制分段

有时，你可能希望按某个任意值对速率限制进行分段。例如，你可能希望允许用户按每个 IP 地址每分钟访问某个给定路由 100 次。要实现这一点，可以在构建速率限制时使用 `by` 方法：

```php
RateLimiter::for('uploads', function (Request $request) {
    return $request->user()->vipCustomer()
        ? Limit::none()
        : Limit::perMinute(100)->by($request->ip());
});
```



为了用另一个示例说明此功能，我们可以将路由访问限制为：已认证用户按用户 ID 每分钟 100 次，访客按 IP 地址每分钟 10 次：

```php
RateLimiter::for('uploads', function (Request $request) {
    return $request->user()
        ? Limit::perMinute(100)->by($request->user()->id)
        : Limit::perMinute(10)->by($request->ip());
});
```

#### 多个速率限制

如果需要，你可以为给定的速率限制器配置返回一个速率限制数组。每个速率限制都会根据它们在数组中的排列顺序，对路由进行评估：

```php
RateLimiter::for('login', function (Request $request) {
    return [
        Limit::perMinute(500),
        Limit::perMinute(3)->by($request->input('email')),
    ];
});
```

如果你正在分配多个使用相同 `by` 值分段的速率限制，则应确保每个 `by` 值都是唯一的。实现这一点最简单的方法是为传递给 `by` 方法的值添加前缀：

```php
RateLimiter::for('uploads', function (Request $request) {
    return [
        Limit::perMinute(10)->by('minute:'.$request->user()->id),
        Limit::perDay(1000)->by('day:'.$request->user()->id),
    ];
});
```

#### 基于响应的速率限制

除了限制传入请求的速率之外，Laravel 还允许你使用 `after` 方法基于响应进行速率限制。当你只想将某些响应计入速率限制时，这会很有用，例如验证错误、404 响应或其他特定的 HTTP 状态码。

`after` 方法接收一个闭包，该闭包会接收响应，并且如果该响应应该计入速率限制，则应返回 `true`；如果应该被忽略，则返回 `false`。这在防止枚举攻击时尤其有用，例如限制连续的 404 响应；或者允许用户重试未通过验证的请求，而不会耗尽某个端点的速率限制，因为该端点本应只限制成功的操作：

```php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\RateLimiter;
use Symfony\Component\HttpFoundation\Response;

RateLimiter::for('resource-not-found', function (Request $request) {
    return Limit::perMinute(10)
        ->by($request->user()?->id ?: $request->ip())
        ->after(function (Response $response) {
            // 仅将 404 响应计入速率限制，以防止枚举...
            return $response->status() === 404;
        });
});
```



### 将速率限制器附加到路由

可以使用 `throttle` [中间件](/docs/laravel/13.x/middleware) 将速率限制器附加到路由或路由组。`throttle` 中间件接收你希望分配给该路由的速率限制器名称：

```php
Route::middleware(['throttle:uploads'])->group(function () {
    Route::post('/audio', function () {
        // ...
    });

    Route::post('/video', function () {
        // ...
    });
});
```

#### 使用 Redis 进行节流

默认情况下，`throttle` 中间件被映射到 `Illuminate\Routing\Middleware\ThrottleRequests` 类。不过，如果你使用 Redis 作为应用程序的缓存驱动，你可能希望指示 Laravel 使用 Redis 来管理速率限制。为此，你应该在应用程序的 `bootstrap/app.php` 文件中使用 `throttleWithRedis` 方法。该方法会将 `throttle` 中间件映射到 `Illuminate\Routing\Middleware\ThrottleRequestsWithRedis` 中间件类：

```php
->withMiddleware(function (Middleware $middleware): void {
    $middleware->throttleWithRedis();
    // ...
})
```

## 表单方法伪造

HTML 表单不支持 `PUT`、`PATCH` 或 `DELETE` 操作。因此，当定义从 HTML 表单调用的 `PUT`、`PATCH` 或 `DELETE` 路由时，你需要向表单添加一个隐藏的 `_method` 字段。通过 `_method` 字段发送的值将被用作 HTTP 请求方法：

```blade
<form action="/example" method="POST">
    <input type="hidden" name="_method" value="PUT">
    <input type="hidden" name="_token" value="{{ csrf_token() }}">
</form>
```

为了方便起见，你可以使用 `@method` [Blade 指令](/docs/laravel/13.x/blade) 来生成 `_method` 输入字段：

```blade
<form action="/example" method="POST">
    @method('PUT')
    @csrf
</form>
```



## 访问当前路由

你可以使用 `Route` 门面上的 `current`、`currentRouteName` 和 `currentRouteAction` 方法来访问处理传入请求的路由信息：

```php
use Illuminate\Support\Facades\Route;

$route = Route::current(); // Illuminate\Routing\Route
$name = Route::currentRouteName(); // string
$action = Route::currentRouteAction(); // string
```

你可以参考 [Route 门面底层类](https://api.laravel.com/docs/laravel/13.x/Illuminate/Routing/Router.html) 和 [Route 实例](https://api.laravel.com/docs/laravel/13.x/Illuminate/Routing/Route.html) 的 API 文档，以查看路由器和路由类上可用的所有方法。

## 跨源资源共享（CORS）

Laravel 可以根据你配置的值，自动响应 CORS `OPTIONS` HTTP 请求。`OPTIONS` 请求会由 `HandleCors` [中间件](/docs/laravel/13.x/middleware) 自动处理，该中间件会自动包含在应用程序的全局中间件栈中。

有时，你可能需要自定义应用程序的 CORS 配置值。你可以使用 `config:publish` Artisan 命令发布 `cors` 配置文件来实现：

```shell
php artisan config:publish cors
```

该命令会在应用程序的 `config` 目录中放置一个 `cors.php` 配置文件。

> [!注意]
> 有关 CORS 和 CORS 标头的更多信息，请查阅 [MDN 关于 CORS 的 Web 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#The_HTTP_response_headers)。

## 路由缓存

将应用程序部署到生产环境时，你应该充分利用 Laravel 的路由缓存。使用路由缓存将大幅减少注册应用程序所有路由所需的时间。要生成路由缓存，请执行 `route:cache` Artisan 命令：

```shell
php artisan route:cache
```

运行此命令后，缓存的路由文件将在每次请求时被加载。请记住，如果你添加了任何新路由，就需要重新生成新的路由缓存。因此，你应该只在项目部署期间运行 `route:cache` 命令。

你可以使用 `route:clear` 命令清除路由缓存：

```shell
php artisan route:clear
```