---

name: laravel-patterns description: "Laravel架构模式、路由/控制器、Eloquent ORM、服务层、队列、事件、缓存和API资源，用于生产应用。" origin: ECC

Laravel 开发模式

用于可扩展、可维护应用的生产级Laravel架构模式。

何时使用

• 构建Laravel Web应用或API
• 组织控制器、服务和领域逻辑
• 使用Eloquent模型和关系
• 设计带资源和分页的API
• 添加队列、事件、缓存和后台任务

工作原理

• 围绕清晰边界组织应用（控制器 -> 服务/动作 -> 模型）
• 使用显式绑定和作用域绑定保持路由可预测；仍通过授权进行访问控制
• 使用类型化模型、转换和作用域保持领域逻辑一致
• 将IO密集工作放入队列，缓存昂贵的读取
• 在 config/* 中集中配置，保持环境显式

示例

项目结构

app/
├── Actions/            # 单一用途用例
├── Console/
├── Events/
├── Http/
│   ├── Controllers/
│   ├── Middleware/
│   ├── Requests/       # 表单请求验证
│   └── Resources/      # API资源
├── Jobs/
├── Models/
├── Policies/
├── Providers/
├── Services/           # 协调领域服务
└── Support/
config/
database/
├── factories/
├── migrations/
└── seeders/
routes/
├── api.php
├── web.php
└── console.php

控制器 -> 服务 -> 动作

保持控制器精简。将编排放在服务中，单一用途逻辑放在动作中。

final class CreateOrderAction
{
    public function __construct(private OrderRepository $orders) {}

    public function handle(CreateOrderData $data): Order
    {
        return $this->orders->create($data);
    }
}

Eloquent 最佳实践

// 使用作用域
class Order extends Model
{
    public function scopePending(Builder $query): Builder
    {
        return $query->where('status', 'pending');
    }

    public function scopeForUser(Builder $query, User $user): Builder
    {
        return $query->where('user_id', $user->id);
    }
}

// 使用转换
protected $casts = [
    'amount' => 'decimal:2',
    'metadata' => 'array',
    'shipped_at' => 'datetime',
];

API资源

class OrderResource extends JsonResource
{
    public function toArray(Request $request): array
    {
        return [
            'id' => $this->id,
            'status' => $this->status,
            'total' => $this->total,
            'items' => OrderItemResource::collection($this->whenLoaded('items')),
        ];
    }
}

队列和任务

class ProcessOrderJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(private Order $order) {}

    public function handle(): void
    {
        // 处理订单逻辑
    }
}

缓存模式

$products = Cache::remember('products:featured', 3600, function () {
    return Product::featured()->with('category')->get();
});