Laravel Architecture Patterns

Оптимизируйте разработку на Laravel с Claude Code. Освойте шаблоны продакшн-уровня для Eloquent, сервисных слоёв, API-ресурсов и масштабируемой PHP-архитектуры.

Разработка API ★ 172,009 GitHub (172,009 ★)

Этот навык предоставляет специализированные рекомендации по созданию масштабируемых и поддерживаемых Laravel-приложений за счет четкого разделения контроллеров, сервисов и моделей. Он помогает разработчикам внедрять профессиональные шаблоны для Eloquent ORM, ограниченных привязок маршрутов, DTO-запросов и надежной фоновой обработки. Создаете ли вы сложные REST API или монолитные веб-приложения — этот навык гарантирует, что ваша кодовая база соответствует лучшим отраслевым практикам производительности, безопасности и долгосрочной сопровождаемости.

Ключевые возможности

01Оптимизированные стратегии очередей, событий и кэширования для производственной производительности

02172 009 звезд на GitHub

03Стандартизированные структуры API Resource с единообразной пагинацией и метаданными

04Продвинутые шаблоны Eloquent ORM, включая пользовательские касты и объекты запросов

05Безопасные ограниченные привязки маршрутов для предотвращения утечек данных между арендаторами

06Архитектура слоя Service-Action для чистой, тестируемой бизнес-логики

Примеры использования

01Рефакторинг «толстых» контроллеров в чистые классы Service и Action

02Оптимизация производительности базы данных через жадную загрузку и специализированные области запросов

03Создание безопасных многопользовательских Laravel API с требованиями к сложным отношениям

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

Laravel 开发模式

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

适用场景

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

工作原理

围绕清晰的边界（控制器 -> 服务/操作 -> 模型）构建应用。
使用显式绑定和作用域绑定来保持路由可预测；同时仍强制执行授权以实现访问控制。
倾向于使用类型化模型、转换器和作用域来保持领域逻辑一致。
将 IO 密��型工作放在队列中，并缓存昂贵的读取操作。
将配置集中在 config/* 中，并保持环境配置显式化。

示例

项目结构

使用具有清晰层级边界（HTTP、服务/操作、模型）的常规 Laravel 布局。

控制器 -> 服务 -> 操作

保持控制器精简。将编排逻辑放在服务中，将单一职责逻辑放在操作中。

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

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

final class OrdersController extends Controller
{
    public function __construct(private CreateOrderAction $createOrder) {}

    public function store(StoreOrderRequest $request): JsonResponse
    {
        $order = $this->createOrder->handle($request->toDto());

        return response()->json([
            'success' => true,
            'data' => OrderResource::make($order),
            'error' => null,
            'meta' => null,
        ], 201);
    }
}

路由与控制器

为了清晰起见，优先使用路由模型绑定和资源控制器。

use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->group(function () {
    Route::apiResource('projects', ProjectController::class);
});

路由模型绑定（作用域）

使用作用域绑定来防止跨租户访问。

Route::scopeBindings()->group(function () {
    Route::get('/accounts/{account}/projects/{project}', [ProjectController::class, 'show']);
});

嵌套路由和绑定名称

保持前缀和路径一致，避免双重嵌套（例如 conversation 与 conversations）。
使用与绑定模型匹配的单一参数名（例如，{conversation} 对应 Conversation）。
嵌套时优先使用作用域绑定以强制执行父子关系。

use App\Http\Controllers\Api\ConversationController;
use App\Http\Controllers\Api\MessageController;
use Illuminate\Support\Facades\Route;

Route::middleware('auth:sanctum')->prefix('conversations')->group(function () {
    Route::post('/', [ConversationController::class, 'store'])->name('conversations.store');

    Route::scopeBindings()->group(function () {
        Route::get('/{conversation}', [ConversationController::class, 'show'])
            ->name('conversations.show');

        Route::post('/{conversation}/messages', [MessageController::class, 'store'])
            ->name('conversation-messages.store');

        Route::get('/{conversation}/messages/{message}', [MessageController::class, 'show'])
            ->name('conversation-messages.show');
    });
});

如果希望参数解析为不同的模型类，请定义显式绑定。对于自定义绑定逻辑，请使用 Route::bind() 或在模型上实现 resolveRouteBinding()。

use App\Models\AiConversation;
use Illuminate\Support\Facades\Route;

Route::model('conversation', AiConversation::class);

服务容器绑定

在服务提供者中将接口绑定到实现，以实现清晰的依赖关系连接。

use App\Repositories\EloquentOrderRepository;
use App\Repositories\OrderRepository;
use Illuminate\Support\ServiceProvider;

final class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(OrderRepository::class, EloquentOrderRepository::class);
    }
}

Eloquent 模型模式

模型配置

final class Project extends Model
{
    use HasFactory;

    protected $fillable = ['name', 'owner_id', 'status'];

    protected $casts = [
        'status' => ProjectStatus::class,
        'archived_at' => 'datetime',
    ];

    public function owner(): BelongsTo
    {
        return $this->belongsTo(User::class, 'owner_id');
    }

    public function scopeActive(Builder $query): Builder
    {
        return $query->whereNull('archived_at');
    }
}

自定义转换器与值对象

使用枚举或值对象进行严格类型化。

use Illuminate\Database\Eloquent\Casts\Attribute;

protected $casts = [
    'status' => ProjectStatus::class,
];

protected function budgetCents(): Attribute
{
    return Attribute::make(
        get: fn (int $value) => Money::fromCents($value),
        set: fn (Money $money) => $money->toCents(),
    );
}

预加载以避免 N+1 问题

$orders = Order::query()
    ->with(['customer', 'items.product'])
    ->latest()
    ->paginate(25);

用于复杂筛选的查询对象

final class ProjectQuery
{
    public function __construct(private Builder $query) {}

    public function ownedBy(int $userId): self
    {
        $query = clone $this->query;

        return new self($query->where('owner_id', $userId));
    }

    public function active(): self
    {
        $query = clone $this->query;

        return new self($query->whereNull('archived_at'));
    }

    public function builder(): Builder
    {
        return $this->query;
    }
}

全局作用域与软删除

使用全局作用域进行默认筛选，并使用 SoftDeletes 处理可恢复的记录。对于同一筛选器，请使用全局作用域或命名作用域中的一种，除非你打算实现分层行为。

use Illuminate\Database\Eloquent\SoftDeletes;
use Illuminate\Database\Eloquent\Builder;

final class Project extends Model
{
    use SoftDeletes;

    protected static function booted(): void
    {
        static::addGlobalScope('active', function (Builder $builder): void {
            $builder->whereNull('archived_at');
        });
    }
}

用于可重用筛选器的查询作用域

use Illuminate\Database\Eloquent\Builder;

final class Project extends Model
{
    public function scopeOwnedBy(Builder $query, int $userId): Builder
    {
        return $query->where('owner_id', $userId);
    }
}

// In service, repository etc.
$projects = Project::ownedBy($user->id)->get();

用于多步更新的数据库事务

use Illuminate\Support\Facades\DB;

DB::transaction(function (): void {
    $order->update(['status' => 'paid']);
    $order->items()->update(['paid_at' => now()]);
});

数据库迁移

命名约定

文件名使用时间戳：YYYY_MM_DD_HHMMSS_create_users_table.php
迁移使用匿名类（无命名类）；文件名传达意图
表名默认为 snake_case 且为复数形式

迁移示例

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('orders', function (Blueprint $table): void {
            $table->id();
            $table->foreignId('customer_id')->constrained()->cascadeOnDelete();
            $table->string('status', 32)->index();
            $table->unsignedInteger('total_cents');
            $table->timestamps();
        });
    }

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

表单请求与验证

将验证逻辑放在表单请求中，并将输入转换为 DTO。

use App\Models\Order;

final class StoreOrderRequest extends FormRequest
{
    public function authorize(): bool
    {
        return $this->user()?->can('create', Order::class) ?? false;
    }

    public function rules(): array
    {
        return [
            'customer_id' => ['required', 'integer', 'exists:customers,id'],
            'items' => ['required', 'array', 'min:1'],
            'items.*.sku' => ['required', 'string'],
            'items.*.quantity' => ['required', 'integer', 'min:1'],
        ];
    }

    public function toDto(): CreateOrderData
    {
        return new CreateOrderData(
            customerId: (int) $this->validated('customer_id'),
            items: $this->validated('items'),
        );
    }
}

API 资源

使用资源和分页保持 API 响应一致。

$projects = Project::query()->active()->paginate(25);

return response()->json([
    'success' => true,
    'data' => ProjectResource::collection($projects->items()),
    'error' => null,
    'meta' => [
        'page' => $projects->currentPage(),
        'per_page' => $projects->perPage(),
        'total' => $projects->total(),
    ],
]);

事件、任务和队列

为副作用（邮件、分析）触发领域事件
使用队列任务处理耗时工作（报告、导出、Webhook）
优先使用具有重试和退避机制的幂等处理器

缓存

缓存读密集型端点和昂贵查询
在模型事件（创建/更新/删除）时使缓存失效
缓存相关数据时使用标签以便于失效

配置与环境

将机密信息保存在 .env 中，将配置保存在 config/*.php 中
使用按环境配置覆盖，并在生产环境中使用 config:cache

🏗 Что это

Этот скилл — сборник production-ready паттернов для Laravel, которые помогают строить масштабируемые и поддерживаемые приложения. Он охватывает типовую структуру проекта, разделение ответственности (контроллеры → сервисы → действия), работу с Eloquent (модели, скоупы, касты), API-ресурсы, очереди, события, кеширование и best practices для роутинга и валидации.

⚙ Как работает

🧱 Структура проекта

Рекомендуется разделять код на чёткие слои: HTTP (контроллеры, Middleware, Form Requests, API Resources), Services, Actions, Models, Jobs, Events и т.д. Пример базовой структуры:

app/
├── Actions/          # одноцелевые use case
├── Http/
│   ├── Controllers/
│   ├── Requests/
│   └── Resources/
├── Services/         # оркестрация
├── Models/
└── ...
config/
database/

🎯 Контроллер → Сервис → Action

Контроллеры остаются тонкими — они только принимают запрос, вызывают сервис/action и возвращают ответ. Сервис координирует несколько действий, а Action — единичная операция (например, "создать заказ").

// Action
final class CreateOrderAction {
    public function __construct(private OrderRepository $orders) {}
    public function handle(CreateOrderData $data): Order {
        return $this->orders->create($data);
    }
}
// Контроллер
final class OrdersController extends Controller {
    public function store(StoreOrderRequest $request): JsonResponse {
        $order = $this->createOrder->handle($request->toDto());
        return response()->json([...], 201);
    }
}

🚦 Роутинг и привязка моделей

Используются apiResource и scopeBindings для автоматической привязки моделей и предотвращения доступа одного тенанта к данным другого.
Имена параметров ({conversation}) должны совпадать с именем модели.
Если нужна кастомная привязка — Route::model() или resolveRouteBinding().

🗄 Eloquent: модели, касты, скоупы

Модели: $fillable, $casts (включая Enum и Value Object), отношения.
Скоупы: именованные (scopeActive) или глобальные (в booted).
Частое использование SoftDeletes для мягкого удаления.
Запросы пагинируются с with() для избежания N+1.
Для сложной фильтрации — отдельный Query-объект, клонирующий билдер.

✅ Форм-реквесты и DTO

Валидация выносится в отдельные классы FormRequest, которые также могут возвращать DTO (toDto()). Это улучшает переиспользуемость и тестируемость.

📡 API-ресурсы

Используются Resource и Resource::collection для единого формата ответа: {success, data, error, meta}. Пагинация передаётся через meta (page, per_page, total).

🕒 События, Jobs, Кеш

События — для побочных эффектов (уведомления, аналитика).
Jobs — для тяжёлой работы (отчёты, вебхуки).
Кеш — для read-heavy запросов; инвалидация по событиям модели.

⚙ Конфигурация

Секреты в .env, остальное в config/*.php.
Использовать config:cache на продакшене.

🔍 Когда использовать

Когда нужно построить новое Laravel-приложение с нуля и сразу заложить архитектуру, которая не развалится при росте.
Если в проекте уже есть хаотичная структура — паттерны помогут рефакторить постепенно.
Для API, где важна консистентность ответов и лёгкая поддержка.

💡 Важно знать

Не следуйте слепо — паттерны нужно адаптировать под конкретную задачу. Например, для простого CRUD можно обойтись без отдельного Action.
Избегайте преждевременной абстракции — начинайте с контроллера и выносите логику только когда она повторяется или усложняется.
Очереди и события — используйте для асинхронных задач, но не злоупотребляйте: каждая очередь — дополнительная точка отказа.
Кеш — всегда продумывайте стратегию инвалидации, иначе данные устареют.
Формальные запросы — отлично, но не смешивайте валидацию с бизнес-логикой.

Этот скилл — не жёсткий стандарт, а набор проверенных практик, которые помогут команде говорить на одном языке и быстрее вводить новичков в курс дела.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code laravel-patterns

Источник: https://mcpmarket.com/tools/skills/laravel-architecture-patterns-4