路由 · laravel 5.4

<article><h1>Laravel HTTP 路由功能</h1><ul><li><a href="#basic-routing">基本路由</a></li><li><a href="#route-parameters">路由参数</a><ul><li><a href="#required-parameters">必选路由参数</a></li><li><a href="#parameters-optional-parameters">可选路由参数</a></li><li><a href="#parameters-regular-expression-constraints">正则表达式约束</a></li></ul></li><li><a href="#named-routes">命名路由</a></li><li><a href="#route-groups">路由组</a><ul><li><a href="#route-group-middleware">中间件</a></li><li><a href="#route-group-namespaces">命名空间</a></li><li><a href="#route-group-sub-domain-routing">子域名路由</a></li><li><a href="#route-group-prefixes">路由前缀</a></li></ul></li><li><a href="#route-model-binding">路由模型绑定</a><ul><li><a href="#implicit-binding">隐式绑定</a></li><li><a href="#explicit-binding">显式绑定</a></li></ul></li><li><a href="#form-method-spoofing">表单方法伪造</a></li><li><a href="#accessing-the-current-route">获取当前路由信息</a></li></ul><a name="basic-routing"></a><h2><a href="#basic-routing">基本路由</a></h2>构建最基本的路由只需要一个 URI 与一个 <code class=" language-php">闭包</code>，这里提供了一个非常简单优雅的定义路由的方法：<pre class=" language-php"><code class=" language-php">Route::get('foo', function () { return 'Hello World'; });</code></pre><h4>默认路由文件</h4>所有的 Laravel 路由都在 <code class=" language-php">routes</code> 目录中的路由文件中定义，这些文件都由框架自动加载。在 <code class=" language-php">routes/web.php</code> 文件中定义你的 web 页面路由。这些路由都会应用 <code class=" language-php">web</code> 中间件组，其提供了诸如 <code class=" language-php">Session</code> 和 <code class=" language-php">CSRF</code> 保护等特性。定义在 <code class=" language-php">routes/api.php</code> 中的路由都是无状态的，并且会应用 <code class=" language-php">api</code> 中间件组。大多数的应用构建，都是以在 <code class=" language-php">routes/web.php</code> 文件定义路由开始的。<h4>可用的路由方法</h4>我们可以注册路由来响应所有的 HTTP 操作：<pre class=" language-php"><code class=" language-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);</code></pre>有的时候你可能需要注册一个可响应多个 HTTP 方法的路由，这时你可以使用 <code class=" language-php">match</code> 方法，也可以使用 <code class=" language-php">any</code> 方法注册一个实现响应所有 HTTP 的请求的路由：<pre class=" language-php"><code class=" language-php">Route::match(['get', 'post'], '/', function () { // }); Route::any('foo', function () { // });</code></pre><h4>CSRF 保护</h4>任何指向 <code class=" language-php">web</code> 中 <code class=" language-php">POST</code>, <code class=" language-php">PUT</code> 或 <code class=" language-php">DELETE</code> 路由的 HTML 表单请求都应该包含一个 CSRF 令牌，否则，这个请求将会被拒绝。更多的关于 CSRF 的说明在 <a href="/docs/5.4/csrf">CSRF 说明文档</a>：<pre class=" language-php"><code class=" language-php"><form method="POST" action="/profile"> {{ csrf_field() }} ... </form></code></pre><a name="route-parameters"></a><h2><a href="#route-parameters">路由参数</a></h2><a name="required-parameters"></a><h3>必选路由参数</h3>当然，有时我们需要在路由中捕获一些 URL 片段。例如，我们需要从 URL 中捕获用户的 ID ，我们可以这样定义路由参数：<pre class=" language-php"><code class=" language-php">Route::get('user/{id}', function ($id) { return 'User '.$id; });</code></pre>也可以根据需要在路由中定义多个参数：<pre class=" language-php"><code class=" language-php">Route::get('posts/{post}/comments/{comment}', function ($postId, $commentId) { // });</code></pre>路由的参数通常都会被放在 <code class=" language-php">{}</code> 内，并且参数名只能为字母，当运行路由时，参数会通过路由闭包来传递。<blockquote>注意： 路由参数不能包含 <code class=" language-php">-</code> 字符。请用下划线 (<code class=" language-php">_</code>) 替换。</blockquote><a name="parameters-optional-parameters"></a><h3>可选路由参数</h3>声明路由参数时，如需指定该参数为可选，可以在参数后面加上 <code class=" language-php">?</code> 来实现，但是相应的变量必须有默认值：<pre class=" language-php"><code class=" language-php">Route::get('user/{name?}', function ($name = null) { return $name; }); Route::get('user/{name?}', function ($name = 'John') { return $name; });</code></pre><a name="parameters-regular-expression-constraints"></a><h3>正则表达式约束</h3>你可以使用 <code class=" language-php">where</code> 方法来规范你的路由参数格式。<code class=" language-php">where</code> 方法接受参数名称和定义参数约束规则的正则表达式：<pre class=" language-php"><code class=" language-php">Route::get('user/{name}', function ($name) { // })->where('name', '[A-Za-z]+'); Route::get('user/{id}', function ($id) { // })->where('id', '[0-9]+'); Route::get('user/{id}/{name}', function ($id, $name) { // })->where(['id' => '[0-9]+', 'name' => '[a-z]+']);</code></pre><a name="parameters-global-constraints"></a><h4>全局约束</h4>如果你希望路由参数在全局范围内都遵循一个确定的正则表达式约束，则可以使用 <code class=" language-php">pattern</code> 方法。你应该在 <code class=" language-php">RouteServiceProvider</code> 的 <code class=" language-php">boot</code> 方法里定义这些模式：<pre class=" language-php"><code class=" language-php">/** * 定义你的路由模型绑定, pattern 过滤器等。 * * @return void */ public function boot() { Route::pattern('id', '[0-9]+'); parent::boot(); }</code></pre>Pattern 一旦被定义，便会自动应用到所有使用该参数名称的路由上：<pre class=" language-php"><code class=" language-php">Route::get('user/{id}', function ($id) { // 仅在 {id} 为数字时执行... });</code></pre><a name="named-routes"></a><h2><a href="#named-routes">命名路由</a></h2>命名路由可以方便的生成 <code class=" language-php">URL</code> 或者重定向，你可以在定义路由后使用 <code class=" language-php">name</code> 方法实现：<pre class=" language-php"><code class=" language-php">Route::get('user/profile', function () { // })->name('profile');</code></pre>你还可以为控制器方法指定路由名称：<pre class=" language-php"><code class=" language-php">Route::get('user/profile', 'UserController@showProfile')->name('profile');</code></pre><h4>为命名路由生成 <code class=" language-php">URL</code></h4>为路由指定了名称后，我们可以使用全局辅助函数 <code class=" language-php">route</code> 来生成 <code class=" language-php">URL</code> 或者重定向到该条路由：<pre class=" language-php"><code class=" language-php">// 生成 URL... $url = route('profile'); // 生成重定向... return redirect()->route('profile');</code></pre>如果是有定义参数的命名路由，可以把参数作为 <code class=" language-php">route</code> 函数的第二个参数传入，指定的参数将会自动插入到 <code class=" language-php">URL</code> 中对应的位置：<pre class=" language-php"><code class=" language-php">Route::get('user/{id}/profile', function ($id) { // })->name('profile'); $url = route('profile', ['id' => 1]);</code></pre><a name="route-groups"></a><h2><a href="#route-groups">路由组</a></h2>路由组允许共享路由属性，例如中间件和命名空间等，我们没有必要为每个路由单独设置共有属性，共有属性会以数组的形式放到 <code class=" language-php">Route::group</code> 方法的第一个参数中。<a name="route-group-middleware"></a><h3>中间件</h3>要给路由组中定义的所有路由分配中间件，可以在路由组中使用 <code class=" language-php">middleware</code> 键，中间件将会依照列表内指定的顺序运行：<pre class=" language-php"><code class=" language-php">Route::group(['middleware' => 'auth'], function () { Route::get('/', function () { // 使用 `Auth` 中间件 }); Route::get('user/profile', function () { // 使用 `Auth` 中间件 }); });</code></pre><a name="route-group-namespaces"></a><h3>命名空间</h3>另一个常见的例子是，为控制器组指定公共的 <code class=" language-php">PHP</code> 命名空间。这时使用 <code class=" language-php">namespace</code> 参数来指定组内所有控制器的公共命名空间：<pre class=" language-php"><code class=" language-php">Route::group(['namespace' => 'Admin'], function () { // 在 "App\Http\Controllers\Admin" 命名空间下的控制器 });</code></pre>请记住，默认 <code class=" language-php">RouteServiceProvider</code> 会在命名空间组中引入你的路由文件，让你不用指定完整的 <code class=" language-php">App\Http\Controllers</code> 命名空间前缀就能注册控制器路由，因此，我们在定义的时候只需要指定命名空间 <code class=" language-php">App\Http\Controllers</code> 以后的部分。<a name="route-group-sub-domain-routing"></a><h3>子域名路由</h3>路由组也可以用作子域名的通配符，子域名可以像 URI 一样当作路由组的参数，因此允许把捕获的子域名一部分用于我们的路由或控制器。可以使用路由组属性的 <code class=" language-php">domain</code> 键声明子域名。<pre class=" language-php"><code class=" language-php">Route::group(['domain' => '{account}.myapp.com'], function () { Route::get('user/{id}', function ($account, $id) { // }); });</code></pre><a name="route-group-prefixes"></a><h3>路由前缀</h3>通过路由组数组属性中的 <code class=" language-php">prefix</code> 键可以给每个路由组中的路由加上指定的 URI 前缀，例如，我们可以给路由组中所有的 URI 加上路由前缀 <code class=" language-php">admin</code> :<pre class=" language-php"><code class=" language-php">Route::group(['prefix' => 'admin'], function () { Route::get('users', function () { // 匹配包含 "/admin/users" 的 URL }); });</code></pre><a name="route-model-binding"></a><h2><a href="#route-model-binding">路由模型绑定</a></h2>当向路由控制器中注入模型 ID 时，我们通常需要查询这个 ID 对应的模型，Laravel 路由模型绑定提供了一个方便的方法自动将模型注入到我们的路由中，例如，除了注入一个用户的 ID，你也可以注入与指定 ID 匹配的完整 <code class=" language-php">User</code> 类实例。<a name="implicit-binding"></a><h3>隐式绑定</h3>Laravel 会自动解析定义在路由或控制器方法（方法包含和路由片段匹配的已声明类型变量）中的 Eloquent 模型，例如：<pre class=" language-php"><code class=" language-php">Route::get('api/users/{user}', function (App\User $user) { return $user->email; });</code></pre>在这个例子中，由于类型声明了 Eloquent 模型 <code class=" language-php">App\User</code>，对应的变量名 <code class=" language-php">$user</code> 会匹配路由片段中的 <code class=" language-php">{user}</code>，这样，Laravel 会自动注入与请求 URI 中传入的 ID 对应的用户模型实例。如果数据库中找不到对应的模型实例，将会自动生成产生一个 404 HTTP 响应。<h4>自定义键名</h4>如果你想要隐式模型绑定除 <code class=" language-php">id</code> 以外的数据库字段，你可以重写 Eloquent 模型类的 <code class=" language-php">getRouteKeyName</code> 方法：<pre class=" language-php"><code class=" language-php">/** * 为路由模型获取键名 * * @return string */ public function getRouteKeyName() { return 'slug'; }</code></pre><a name="explicit-binding"></a><h3>显式绑定</h3>使用路由的 <code class=" language-php">model</code> 方法来为已有参数声明 class 。你应该在 <code class=" language-php">RouteServiceProvider</code> 类中的 <code class=" language-php">boot</code> 方法内定义这些显式绑定：<pre class=" language-php"><code class=" language-php">public function boot() { parent::boot(); Route::model('user', App\User::class); }</code></pre>接着，定义包含 <code class=" language-php">{user}</code> 参数的路由：<pre class=" language-php"><code class=" language-php">Route::get('profile/{user}', function (App\User $user) { // });</code></pre>因为我们已经绑定 <code class=" language-php">{user}</code> 参数至 <code class=" language-php">App\User</code> 模型，所以 <code class=" language-php">User</code> 实例将被注入该路由。举个例子，一个至 <code class=" language-php">profile/1</code> 的请求会注入 ID 为 1 的 <code class=" language-php">User</code> 实例。<blockquote>注意：如果在数据库不存在对应 ID 的数据，就会自动抛出一个 404 异常。</blockquote><h4>自定义解析逻辑</h4>如果你想要使用自定义的解析逻辑，需要使用 <code class=" language-php">Route::bind</code> 方法，传递到 <code class=" language-php">bind</code> 方法的闭包会获取到 URI 请求参数中的值，并且返回你想要在该路由中注入的类实例：<pre class=" language-php"><code class=" language-php">public function boot() { parent::boot(); Route::bind('user', function ($value) { return App\User::where('name', $value)->first(); }); }</code></pre><a name="form-method-spoofing"></a><h2><a href="#form-method-spoofing">表单方法伪造</a></h2>HTML 表单没有支持 <code class=" language-php">PUT</code>、<code class=" language-php">PATCH</code> 或 <code class=" language-php">DELETE</code> 动作。所以在定义要在 HTML 表单中调用的 <code class=" language-php">PUT</code>、<code class=" language-php">PATCH</code> 或 <code class=" language-php">DELETE</code> 路由时，你将需要在表单中增加隐藏的 <code class=" language-php">_method</code> 字段。 <code class=" language-php">_method</code> 字段的值将被作为 HTTP 的请求方法使用：<pre class=" language-php"><code class=" language-php"><form action="/foo/bar" method="POST"> <input type="hidden" name="_method" value="PUT"> <input type="hidden" name="_token" value="{{ csrf_token() }}"> </form></code></pre>你也可以使用辅助函数 <code class=" language-php">method_field</code> 来生成隐藏的输入字段 <code class=" language-php">_method</code>：<pre class=" language-php"><code class=" language-php">{{ method_field('PUT') }}</code></pre><a name="accessing-the-current-route"></a><h2><a href="#accessing-the-current-route">获取当前路由信息</a></h2>你可以使用 <code class=" language-php">Route</code> 上的 <code class=" language-php">current</code>, <code class=" language-php">currentRouteName</code>, and <code class=" language-php">currentRouteAction</code> 方法来访问处理当前输入请求的路由信息：<pre class=" language-php"><code class=" language-php">$route = Route::current(); $name = Route::currentRouteName(); $action = Route::currentRouteAction();</code></pre>完整的方法列表请参考 <a href="http://laravel.com/api/5.4/Illuminate/Routing/Router.html">Route facade</a> 和 <a href="http://laravel.com/api/5.4/Illuminate/Routing/Route.html">Route 实例</a><h2>译者署名</h2><table><thead><tr><th>用户名</th><th>头像</th><th>职能</th><th>签名</th></tr></thead><tbody><tr><td><a href="https://github.com/zhouzihanntu">@zhouzihanntu</a></td><td><img class="avatar-66 rm-style" src="https://avatars0.githubusercontent.com/u/14007659?v=3&s=460"></td><td>翻译</td><td></td></tr></tbody></table></article>