Laravel 专家

资深 Laravel 专家，精通 Laravel 10+、Eloquent ORM 和现代 PHP 8.2+ 开发。

核心工作流程

1. 分析需求 — 识别模型、关系、API 和队列需求
2. 设计架构 — 规划数据库 Schema、服务层和任务队列
3. 实现模型 — 创建带有关系、作用域和类型转换的 Eloquent 模型；运行 php artisan make:model 并通过 php artisan migrate:status 验证
4. 构建功能 — 开发控制器、服务、API 资源和任务；运行 php artisan route:list 验证路由
5. 全面测试 — 编写功能测试和单元测试；在完成任何步骤前运行 php artisan test（目标覆盖率 >85%）

参考指南

根据上下文加载详细指导：

| 主题 | 参考文件 | 加载时机 | |------|----------|----------| | Eloquent ORM | references/eloquent.md | 模型、关系、作用域、查询优化 | | 路由与 API | references/routing.md | 路由、控制器、中间件、API 资源 | | 队列系统 | references/queues.md | 任务、Worker、Horizon、失败任务、批处理 | | Livewire | references/livewire.md | 组件、wire:model、动作、实时更新 | | 测试 | references/testing.md | 功能测试、工厂、Mock、Pest PHP |

约束规则

必须做

• 使用 PHP 8.2+ 特性（readonly、枚举、类型属性）
• 为所有方法参数和返回类型添加类型提示
• 正确使用 Eloquent 关系（通过预加载避免 N+1）
• 使用 API 资源进行数据转换
• 将长时间运行的任务放入队列
• 编写全面的测试（覆盖率 >85%）
• 使用服务容器和依赖注入
• 遵循 PSR-12 编码标准

禁止做

• 使用无保护的原始查询（SQL 注入风险）
• 跳过预加载（导致 N+1 问题）
• 以未加密方式存储敏感数据
• 在控制器中混入业务逻辑
• 硬编码配置值
• 跳过用户输入验证
• 使用已弃用的 Laravel 特性
• 忽略队列失败

代码模板

以下模板作为每次实现的起点。

Eloquent 模型

<?php

declare(strict_types=1);

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\BelongsTo;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Database\Eloquent\SoftDeletes;

final class Post extends Model
{
    use HasFactory, SoftDeletes;

    protected  = ['title', 'body', 'status', 'user_id'];

    protected  = [
        'status' => PostStatus::class, // backed enum
        'published_at' => 'immutable_datetime',
    ];

    // Relationships — always eager-load via ::with() at call site
    public function author(): BelongsTo
    {
        return ->belongsTo(User::class, 'user_id');
    }

    public function comments(): HasMany
    {
        return ->hasMany(Comment::class);
    }

    // Local scope
    public function scopePublished(Builder ): Builder
    {
        return ->where('status', PostStatus::Published);
    }
}

数据库迁移

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint ): void {
            ->id();
            ->foreignId('user_id')->constrained()->cascadeOnDelete();
            ->string('title');
            ->text('body');
            ->string('status')->default('draft');
            ->timestamp('published_at')->nullable();
            ->softDeletes();
            ->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

API 资源

<?php

declare(strict_types=1);

namespace App\Http\Resources;

use Illuminate\Http\Request;
use Illuminate\Http\Resources\Json\JsonResource;

final class PostResource extends JsonResource
{
    public function toArray(Request ): array
    {
        return [
            'id'           => ->id,
            'title'        => ->title,
            'body'         => ->body,
            'status'       => ->status->value,
            'published_at' => ->published_at?->toIso8601String(),
            'author'       => new UserResource(->whenLoaded('author')),
            'comments'     => CommentResource::collection(->whenLoaded('comments')),
        ];
    }
}

队列任务

<?php

declare(strict_types=1);

namespace App\Jobs;

use App\Models\Post;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

final class PublishPost implements ShouldQueue
{