Laravel Route Model Binding的高级用法：自定义查询逻辑与错误处理

Laravel Route Model Binding 高级用法：自定义查询逻辑与错误处理

大家好，今天我们来深入探讨 Laravel Route Model Binding 的高级用法，重点关注如何自定义查询逻辑以及如何优雅地处理错误。Route Model Binding 是 Laravel 提供的一项非常强大的功能，它能让我们在路由定义中直接注入模型实例，而无需手动进行查询。然而，默认的 Route Model Binding 只能满足一些基本的需求，当我们遇到更复杂的场景时，就需要对其进行自定义。

1. 默认 Route Model Binding 的局限性

默认情况下，Route Model Binding 使用主键 (通常是 id 字段) 来查找模型实例。例如：

use AppModelsPost;
use IlluminateSupportFacadesRoute;

Route::get('/posts/{post}', function (Post $post) {
    return view('posts.show', ['post' => $post]);
});

在这个例子中，Laravel 会自动查找 Post 模型中 id 等于路由参数 {post} 的记录。 这背后的 SQL 大致等价于：

SELECT * FROM posts WHERE id = {post} LIMIT 1;

这种方式简洁高效，但存在一些局限性：

• 只能使用主键： 默认只能通过主键来查找模型，无法使用其他字段。
• 简单的错误处理： 如果找不到模型，默认会抛出一个 ModelNotFoundException 异常，但缺乏更细粒度的控制。
• 缺乏复杂的查询条件： 无法在查询中添加额外的条件，例如仅查找已发布的文章。

为了克服这些局限性，我们需要学习如何自定义 Route Model Binding。

2. 显式绑定：使用 where 方法自定义键名

最简单的自定义 Route Model Binding 的方式是使用 Route::model 或 Route::bind 方法，配合 where 方法指定不同的字段作为键名。

2.1. Route::model 方法

Route::model 方法接受两个参数：路由参数名称和模型类名。它会自动注册一个绑定，并允许我们使用 where 方法来指定用于查找模型的字段。

use AppModelsPost;
use IlluminateSupportFacadesRoute;

Route::model('post', Post::class);

Route::get('/posts/{post:slug}', function (Post $post) {
    return view('posts.show', ['post' => $post]);
})->where('post', '[a-zA-Z0-9-]+'); //可选的正则表达式约束

在这个例子中，我们使用 slug 字段作为查找 Post 模型的键名。 ->where('post', '[a-zA-Z0-9-]+') 这一行是对路由参数 post 的一个正则表达式约束，确保 slug 是一个有效的 slug 格式。 这背后的 SQL 大致等价于：

SELECT * FROM posts WHERE slug = {post} LIMIT 1;

2.2. Route::bind 方法

Route::bind 方法提供了更大的灵活性，允许我们自定义查找模型的逻辑。它接受两个参数：路由参数名称和一个闭包函数。闭包函数接收路由参数的值，并返回一个模型实例，或者 null 如果找不到模型。

use AppModelsPost;
use IlluminateSupportFacadesRoute;

Route::bind('post', function ($value) {
    return Post::where('slug', $value)->first();
});

Route::get('/posts/{post}', function (Post $post) {
    return view('posts.show', ['post' => $post]);
});

在这个例子中，我们使用闭包函数来自定义查找 Post 模型的逻辑，同样是基于 slug 字段。 这背后的 SQL 与 Route::model 例子是相同的。

2.3. 显式绑定与隐式绑定的对比

特性	显式绑定 (Route::model / Route::bind)	隐式绑定 (类型提示)
灵活性	更高，可以完全自定义查询逻辑	较低，仅能使用主键
代码位置	routes/web.php 或 routes/api.php	控制器方法签名
适用场景	需要自定义查询逻辑的场景	简单的基于主键查找
错误处理	默认抛出 ModelNotFoundException，可通过自定义闭包进行覆盖	默认抛出 ModelNotFoundException

3. 隐式绑定：使用 resolveRouteBinding 方法自定义查询逻辑

Laravel 5.6 引入了自定义隐式 Route Model Binding 的能力，允许我们在模型类中定义 resolveRouteBinding 方法，来自定义查找模型的逻辑。 这使得代码更加内聚，模型类本身就包含了如何被路由解析的逻辑。

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class Post extends Model
{
    public function resolveRouteBinding($value, $field = null)
    {
        $field = $field ?: 'id'; // 允许指定字段，默认为 id

        return $this->where($field, $value)->firstOrFail();
    }
}

在这个例子中，我们在 Post 模型中定义了 resolveRouteBinding 方法。该方法接收两个参数：路由参数的值和用于查找模型的字段 (可选，默认为 id)。我们使用 where 方法和 firstOrFail 方法来查找模型，如果找不到模型则抛出 ModelNotFoundException 异常。

现在，我们可以像往常一样使用隐式 Route Model Binding：

use AppModelsPost;
use IlluminateSupportFacadesRoute;

Route::get('/posts/{post}', function (Post $post) {
    return view('posts.show', ['post' => $post]);
});

Route::get('/posts/{post:slug}', function (Post $post) {
    return view('posts.show', ['post' => $post]);
});

第一个路由会使用 id 字段来查找 Post 模型，而第二个路由会使用 slug 字段。 {post:slug} 语法会自动将 slug 作为 resolveRouteBinding 方法的 $field 参数传递。

3.1. resolveChildRouteBinding 方法

除了 resolveRouteBinding 方法，Laravel 还提供了 resolveChildRouteBinding 方法，用于处理嵌套路由中的模型绑定。 例如，假设我们有一个 User 模型和一个 Post 模型，并且用户可以拥有多个文章。 我们可以定义如下路由：

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

在这种情况下，我们需要确保 $post 属于 $user。 我们可以在 Post 模型中定义 resolveChildRouteBinding 方法来实现这个逻辑：

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class Post extends Model
{
    public function resolveChildRouteBinding($childType, $value, $field)
    {
        return $this->where($field, $value)
                    ->where('user_id', $this->parent->id) // 假设存在 parent 属性
                    ->firstOrFail();
    }
}

注意：这个例子中假设 Post 模型有一个 parent 属性，指向其所属的 User 模型。 实际情况可能需要根据你的模型关系进行调整。 为了使 parent 属性生效，需要在 User 模型中建立关联关系：

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class User extends Model
{
    public function posts()
    {
        return $this->hasMany(Post::class);
    }
    public function resolveRouteBinding($value, $field = null)
    {
        $field = $field ?: 'id';
        $model = $this->where($field, $value)->firstOrFail();
        $model->posts->each(function ($post) use ($model){
            $post->parent = $model;
        });
        return $model;
    }
}

resolveChildRouteBinding 会在 resolveRouteBinding 之后被调用，并且 $this->parent 指向父级模型 (在这个例子中是 User 模型)。 这段代码的关键在于在解析 User 模型时，将 User 模型的实例作为 parent 属性赋值给其关联的 Post 模型，以便 resolveChildRouteBinding 方法能够访问到父级模型的信息。

4. 高级查询：使用 Scopes 添加约束

除了自定义键名，我们还可以在查询中添加额外的约束，例如仅查找已发布的文章。 可以使用 Laravel 的 Eloquent Scopes 来实现这一目标。

4.1. 定义 Global Scope

Global Scopes 允许我们为模型的所有查询添加约束。 例如，我们可以创建一个 PublishedScope，用于仅查找 published_at 字段不为空的文章。

namespace AppScopes;

use IlluminateDatabaseEloquentBuilder;
use IlluminateDatabaseEloquentModel;
use IlluminateDatabaseEloquentScope;

class PublishedScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        $builder->whereNotNull('published_at');
    }
}

然后，在 Post 模型中应用这个 Scope：

namespace AppModels;

use AppScopesPublishedScope;
use IlluminateDatabaseEloquentModel;

class Post extends Model
{
    protected static function booted()
    {
        static::addGlobalScope(new PublishedScope);
    }
}

现在，所有针对 Post 模型的查询都会自动包含 whereNotNull('published_at') 条件。

4.2. 定义 Local Scope

Local Scopes 允许我们定义可复用的查询约束。 例如，我们可以创建一个 published Scope，用于仅查找 published_at 字段不为空的文章 (与 Global Scope 类似，但可以手动调用)。

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class Post extends Model
{
    public function scopePublished($query)
    {
        return $query->whereNotNull('published_at');
    }
}

现在，我们可以像这样使用 published Scope：

$posts = Post::published()->get();

4.3. 在 Route Model Binding 中使用 Scope

可以在 resolveRouteBinding 方法中使用 Scope 来添加额外的约束。

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class Post extends Model
{
    public function resolveRouteBinding($value, $field = null)
    {
        $field = $field ?: 'id';

        return $this->published()->where($field, $value)->firstOrFail();
    }
}

在这个例子中，我们使用 published Scope 来确保只查找已发布的文章。

5. 错误处理：自定义异常与响应

默认情况下，当 Route Model Binding 找不到模型时，会抛出一个 ModelNotFoundException 异常。 我们可以自定义这个异常，或者提供更友好的响应。

5.1. 使用 findOrFail 方法

findOrFail 方法会在找不到模型时抛出 ModelNotFoundException 异常。 我们可以使用 try...catch 块来捕获这个异常，并返回自定义的响应。

use AppModelsPost;
use IlluminateSupportFacadesRoute;
use SymfonyComponentHttpKernelExceptionNotFoundHttpException;

Route::get('/posts/{post}', function (Post $post) {
    return view('posts.show', ['post' => $post]);
})->missing(function ($request, $exception) {
    return response()->view('errors.post_not_found', [], 404);
});

在这个例子中，我们使用 missing 方法来处理找不到模型的情况，并返回一个自定义的错误页面 errors.post_not_found。 missing 方法提供了一种更简洁的方式来处理 Route Model Binding 失败的情况。

5.2. 自定义 resolveRouteBinding 方法中的异常

我们可以在 resolveRouteBinding 方法中使用 abort 函数来抛出自定义的 HTTP 异常。

namespace AppModels;

use IlluminateDatabaseEloquentModel;

class Post extends Model
{
    public function resolveRouteBinding($value, $field = null)
    {
        $field = $field ?: 'id';

        $post = $this->where($field, $value)->first();

        if (!$post) {
            abort(404, 'Post not found.');
        }

        return $post;
    }
}

在这个例子中，如果找不到模型，我们会抛出一个 404 异常，并显示一条自定义的消息 "Post not found."。

5.3. 全局异常处理

也可以在 app/Exceptions/Handler.php 文件中全局处理 ModelNotFoundException 异常。

namespace AppExceptions;

use IlluminateFoundationExceptionsHandler as ExceptionHandler;
use IlluminateDatabaseEloquentModelNotFoundException;
use SymfonyComponentHttpKernelExceptionNotFoundHttpException;
use Throwable;

class Handler extends ExceptionHandler
{
    /**
     * A list of the exception types that are not reported.
     *
     * @var array
     */
    protected $dontReport = [
        //
    ];

    /**
     * A list of the inputs that are never flashed for validation exceptions.
     *
     * @var array
     */
    protected $dontFlash = [
        'password',
        'password_confirmation',
    ];

    /**
     * Register the exception handling callbacks for the application.
     *
     * @return void
     */
    public function register()
    {
        $this->renderable(function (ModelNotFoundException $e, $request) {
            return response()->view('errors.model_not_found', [], 404);
        });

        $this->renderable(function (NotFoundHttpException $e, $request) {
            if ($e->getPrevious() instanceof ModelNotFoundException) {
                return response()->view('errors.model_not_found', [], 404);
            }
        });
    }
}

在这个例子中，我们注册了一个 renderable 回调函数，用于处理 ModelNotFoundException 异常，并返回一个自定义的错误页面 errors.model_not_found。 同时，我们也处理了 NotFoundHttpException，并检查其 previous 异常是否为 ModelNotFoundException，如果是，则也返回相同的自定义错误页面。

6. 总结：灵活的 Route Model Binding，更好的代码体验

通过显式绑定、隐式绑定以及 Eloquent Scopes，我们可以灵活地自定义 Route Model Binding 的查询逻辑，满足各种复杂的场景需求。 同时，通过自定义异常处理，我们可以提供更友好的错误提示，提升用户体验。 掌握这些高级用法，能使你的 Laravel 代码更加优雅、健壮。