Laravel 13 路由新特性详解

摘要

Laravel 13 对路由系统进行了多项增强，包括 PHP Attributes 支持和路由模型绑定改进。本文将深入讲解 Laravel 13 的路由新特性，包括：

路由属性详解
路由模型绑定增强
路由组改进
路由缓存优化
实战案例与最佳实践

本文适合希望掌握 Laravel 13 路由新特性的开发者。

1. 路由属性

1.1 基本路由属性

use Illuminate\Routing\Attributes\Get;
use Illuminate\Routing\Attributes\Post;
use Illuminate\Routing\Attributes\Put;
use Illuminate\Routing\Attributes\Delete;
use Illuminate\Routing\Attributes\Patch;

class UserController extends Controller
{
    #[Get('/users')]
    public function index()
    {
        // GET /users
    }
    
    #[Post('/users')]
    public function store()
    {
        // POST /users
    }
    
    #[Get('/users/{user}')]
    public function show(User $user)
    {
        // GET /users/{user}
    }
    
    #[Put('/users/{user}')]
    public function update(User $user)
    {
        // PUT /users/{user}
    }
    
    #[Delete('/users/{user}')]
    public function destroy(User $user)
    {
        // DELETE /users/{user}
    }
}

1.2 路由名称

#[Get('/users', name: 'users.index')]
public function index()
{
    // route('users.index')
}

#[Get('/users/{user}', name: 'users.show')]
public function show(User $user)
{
    // route('users.show', $user)
}

1.3 路由参数约束

use Illuminate\Routing\Attributes\Where;

#[Get('/users/{user}')]
#[Where('user', '[0-9]+')]
public function show(User $user)
{
    // 只匹配数字 ID
}

#[Get('/posts/{post:slug}')]
public function showPost(Post $post)
{
    // 使用 slug 字段解析
}

1.4 路由组属性

use Illuminate\Routing\Attributes\Prefix;
use Illuminate\Routing\Attributes\Domain;
use Illuminate\Routing\Attributes\Middleware;

#[Prefix('api/v1')]
#[Domain('api.example.com')]
#[Middleware(['auth:sanctum', 'throttle:api'])]
class ApiController extends Controller
{
    #[Get('/users')]
    public function users()
    {
        // GET https://api.example.com/api/v1/users
    }
}

2. 路由模型绑定

2.1 隐式绑定

#[Get('/users/{user}')]
public function show(User $user)
{
    // 自动解析 User 模型
}

#[Get('/posts/{post:slug}')]
public function showPost(Post $post)
{
    // 使用 slug 字段解析
}

2.2 显式绑定

// RouteServiceProvider
public function boot()
{
    Route::model('user', User::class);
    Route::bind('post', function ($value) {
        return Post::where('slug', $value)->firstOrFail();
    });
}

2.3 软删除模型

#[Get('/users/{user}')]
public function show(User $user)
{
    // 默认不包含软删除
}

#[Get('/users/{user}')]
public function showWithTrashed(User $user)
{
    // 在控制器中处理
    $user = User::withTrashed()->findOrFail($user->id);
}

2.4 自定义键

class User extends Model
{
    public function getRouteKeyName()
    {
        return 'slug';
    }
}

3. 路由组

3.1 中间件组

#[Middleware(['auth', 'verified'])]
class DashboardController extends Controller
{
    // 所有方法都需要认证和邮箱验证
}

3.2 命名空间组

// 传统方式
Route::namespace('Admin')->group(function () {
    // Admin 命名空间下的控制器
});

3.3 子域名路由

#[Domain('{tenant}.example.com')]
class TenantController extends Controller
{
    #[Get('/dashboard')]
    public function dashboard($tenant)
    {
        // {tenant}.example.com/dashboard
    }
}

4. 资源路由

4.1 API 资源

use Illuminate\Routing\Attributes\ApiResource;

#[ApiResource('users')]
class UserController extends Controller
{
    // 自动创建 index, store, show, update, destroy
}

4.2 资源路由

use Illuminate\Routing\Attributes\Resource;

#[Resource('posts')]
class PostController extends Controller
{
    // 包含 create 和 edit
}

4.3 部分资源

#[ApiResource('users', only: ['index', 'show'])]
class UserController extends Controller
{
    // 只有 index 和 show
}

#[ApiResource('posts', except: ['destroy'])]
class PostController extends Controller
{
    // 除了 destroy
}

5. 路由缓存

5.1 缓存路由

1	php artisan route:cache

5.2 清除缓存

1	php artisan route:clear

5.3 查看路由

1
2
3

php artisan route:list
php artisan route:list --path=api
php artisan route:list --method=POST

6. 实战案例

6.1 RESTful API 路由

<?php

namespace App\Http\Controllers\Api;

use App\Models\Post;
use Illuminate\Routing\Attributes\Get;
use Illuminate\Routing\Attributes\Post;
use Illuminate\Routing\Attributes\Put;
use Illuminate\Routing\Attributes\Delete;
use Illuminate\Routing\Attributes\Prefix;
use Illuminate\Routing\Attributes\Middleware;

#[Prefix('api/v1')]
#[Middleware('auth:sanctum')]
class PostController extends Controller
{
    #[Get('/posts', name: 'api.posts.index')]
    public function index()
    {
        return Post::paginate();
    }
    
    #[Get('/posts/{post}', name: 'api.posts.show')]
    public function show(Post $post)
    {
        return $post;
    }
    
    #[Post('/posts', name: 'api.posts.store')]
    public function store()
    {
        $post = Post::create(request()->validate([
            'title' => 'required',
            'content' => 'required',
        ]));
        
        return response()->json($post, 201);
    }
    
    #[Put('/posts/{post}', name: 'api.posts.update')]
    public function update(Post $post)
    {
        $post->update(request()->validate([
            'title' => 'sometimes|required',
            'content' => 'sometimes|required',
        ]));
        
        return $post;
    }
    
    #[Delete('/posts/{post}', name: 'api.posts.destroy')]
    public function destroy(Post $post)
    {
        $post->delete();
        return response()->noContent();
    }
}

7. 最佳实践

7.1 路由命名规范

// 推荐：使用资源命名
'users.index'
'users.show'
'users.store'
'users.update'
'users.destroy'

// 不推荐
'user-list'
'user-detail'

7.2 路由组织

// 按模块分组
#[Prefix('api/v1/users')]
class UserController {}

#[Prefix('api/v1/posts')]
class PostController {}

#[Prefix('api/v1/comments')]
class CommentController {}