Архитектура и паттерны

SOLID — пять принципов ООП-дизайна, сформулированных Робертом Мартином в 2000-х. Это эвристики, не строгие законы. Цель — уменьшить связанность, увеличить переиспользование, сделать код терпимым к изменениям. Senior следует SOLID не догматически: иногда нарушение принципа — правильное решение.

// Контроллер делает всё
public function store(Request $request)
{
    $validated = $request->validate(['email' => 'required|email']);
    if ($validated['country'] === 'KZ') $tax = $validated['amount'] * 0.12;
    $order = Order::create([...]);
    Mail::to($order->email)->send(new OrderConfirmation($order));
    return response()->json($order);
}

// Каждый класс — одна ответственность
public function store(StoreOrderRequest $request, CreateOrder $action): JsonResponse
{
    $order = $action($request->validated());
    return response()->json(new OrderResource($order), 201);
}

Дополнительные эвристики. GRASP (General Responsibility Assignment Software Patterns) — более общие принципы распределения ответственности (Крэг Ларман). DRY, KISS, YAGNI — короткие правила-якоря для повседневных решений.

// Два метода, похожих на 90%, разная семантика
public function calculateOrderTax(Order $order): int {
    return (int) ($order->total * 0.12);
}
public function calculateRefundTax(Refund $refund): int {
    return (int) ($refund->total * 0.12);
}

// Преждевременное DRY: единая абстракция.
// Если правила для refund изменятся (другие ставки) — придётся ломать.
public function calculateTax(int $amount): int {
    return (int) ($amount * 0.12);
}

// KISS / YAGNI: оставить два метода до третьего случая.
// Эволюция: дублирование → паттерн → абстракция.

Паттерны создания объектов. Решают «как получить экземпляр», когда простой new не подходит: валидация в конструкторе, выбор класса по параметру, тяжёлая инициализация, кеширование.

Большие структуры из меньших объектов. Adapter — согласовать несовместимые интерфейсы; Decorator — добавить функциональность не меняя класс; Facade — упростить сложный API.

Взаимодействие между объектами. Strategy — подмена алгоритма; Observer — уведомление подписчиков; Command — инкапсуляция действия; Template Method — скелет с переопределяемыми шагами.

// Switch на тип — нарушение Open/Closed
public function ship(Order $order, string $carrier): string
{
    return match ($carrier) {
        'dhl'   => $this->shipViaDHL($order),
        'fedex' => $this->shipViaFedEx($order),
        'local' => $this->shipViaLocal($order),
    };
}

// Strategy
interface ShippingStrategy { public function ship(Order $o): string; }
final class DhlStrategy   implements ShippingStrategy { ... }
final class FedExStrategy implements ShippingStrategy { ... }

final class OrderShipper
{
    public function ship(Order $o, ShippingStrategy $s): string
    { return $s->ship($o); }
}

Repository — абстракция хранилища: «дай мне сущность по критериям». Скрывает детали БД от бизнес-логики. В DDD — обязательный паттерн. В Laravel — спорный, поскольку Eloquent уже реализует Active Record + Query Builder.

Практический критерий: если в проекте сложный домен (DDD) или multiple data sources — Repository оправдан. В обычном CRUD — антипаттерн.

// Интерфейс — что нужно бизнес-логике
interface OrderRepository
{
    public function find(int $id): ?Order;
    public function save(Order $order): void;
    public function findUnpaidOlderThan(Carbon $date): Collection;
}

// Eloquent-реализация
final class EloquentOrderRepository implements OrderRepository
{
    public function find(int $id): ?Order
    { return Order::find($id); }

    public function save(Order $order): void
    { $order->save(); }

    public function findUnpaidOlderThan(Carbon $date): Collection
    {
        return Order::where('status', 'pending')
            ->where('created_at', '<', $date)->get();
    }
}

// Bind в Service Provider
$this->app->bind(OrderRepository::class, EloquentOrderRepository::class);

Service Layer — место бизнес-логики. Контроллер тонкий; Service делает оркестрацию между Repositories, внешними API, событиями. DTO — неизменяемая структура для передачи данных между слоями.

// DTO
final class CreateOrderData
{
    public function __construct(
        public readonly int    $userId,
        public readonly array  $items,
        public readonly string $currency,
    ) {}

    public static function fromRequest(StoreOrderRequest $r): self
    {
        return new self(
            userId:   $r->user()->id,
            items:    $r->input('items'),
            currency: $r->string('currency')->value(),
        );
    }
}

// Action
final class CreateOrder
{
    public function __construct(
        private OrderRepository $orders,
        private PaymentGateway  $gateway,
    ) {}

    public function __invoke(CreateOrderData $data): Order
    {
        return DB::transaction(function () use ($data) {
            $order = new Order([...]);
            $this->orders->save($order);
            $this->gateway->charge($order->total, $data->currency);
            return $order;
        });
    }
}

// Controller — тонкий
public function store(StoreOrderRequest $r, CreateOrder $action): JsonResponse
{
    $order = $action(CreateOrderData::fromRequest($r));
    return response()->json(new OrderResource($order), 201);
}

Domain-Driven Design (Эрик Эванс, 2003). Стратегический DDD — о структуре больших систем (Bounded Context). Тактический — о шаблонах внутри одного контекста: Entity, Value Object, Aggregate, Domain Service, Repository, Domain Event.

Clean Architecture (Боб Мартин) и Hexagonal (Алистер Кокберн) ставят в центр бизнес-логику, изолированную от инфраструктуры. БД, веб, очереди — детали, легко заменяемые. Цель: код, тестируемый без БД, переносимый между фреймворками.

Альтернативный взгляд: центр — домен; снаружи — адаптеры через порты (интерфейсы). Каждое внешнее взаимодействие — отдельный port + adapter. Терминологически проще Clean Architecture, идея та же.

// Port — интерфейс, определённый доменом
interface OrderRepository { // в src/Domain/
    public function save(Order $order): void;
}

// Adapter — реализация во внешнем слое
final class EloquentOrderRepository implements OrderRepository
{ // в src/Infrastructure/Persistence/
    public function save(Order $order): void { ... }
}

// Use Case зависит только от Port (инверсия зависимости)
final class CreateOrder
{
    public function __construct(private OrderRepository $repo) {}
}

Микросервис — небольшая автономная программа, отвечающая за одну бизнес-возможность и общающаяся с остальными по сети: HTTP/REST, gRPC или сообщения.

Микросервисная архитектура — построение приложения как набора таких независимых сервисов вместо одного большого.

Модуль внутри монолита — часть одного процесса и одной кодовой базы. Микросервис — отдельно развёртываемый компонент.

Сервис заказов при оформлении может синхронно спросить оплату — ответ нужен сразу. А уведомление отправить асинхронно через очередь: пользователь не должен ждать, пока уйдёт письмо.

Классический сценарий в микросервисах: сервис заказов должен одновременно:

• Сохранить заказ в свою БД (orders).
• Опубликовать событие OrderCreated в брокер (Kafka / RabbitMQ / SNS).

Это две разные системы. Атомарной транзакции между ними не бывает без сложных протоколов вроде 2PC. Значит возможны рассогласованные состояния:

Идея: перенести публикацию в БД. В той же транзакции, что сохраняет заказ, пишем ещё одну строку — в служебную таблицу outbox. Отдельный процесс (relay) читает outbox и публикует события в брокер уже вне транзакции.

1. BEGIN транзакции БД.
2. Сохранение бизнес-данных. INSERT INTO orders ...
3. Сохранение события в outbox. INSERT INTO outbox (event_type, payload_json, aggregate_id, created_at).
4. COMMIT. Либо всё сохранилось, либо ничего — атомарно.
5. Relay-процесс опрашивает outbox, забирает не-отправленные события.
6. Publish в брокер. Успешно → пометить published_at = now() (или удалить строку). Неуспешно → оставить как есть, следующий цикл повторит.

CREATE TABLE outbox (
    id            BIGSERIAL PRIMARY KEY,
    aggregate_type VARCHAR(64)  NOT NULL,   -- 'Order', 'Payment', ...
    aggregate_id   VARCHAR(64)  NOT NULL,   -- для routing и порядка
    event_type     VARCHAR(64)  NOT NULL,   -- 'OrderCreated', 'OrderPaid'
    payload        JSONB        NOT NULL,   -- сериализованное событие
    created_at     TIMESTAMPTZ  NOT NULL DEFAULT now(),
    published_at   TIMESTAMPTZ  NULL              -- NULL = ещё не отправлено
);

-- Индекс для быстрого поиска не-отправленных
CREATE INDEX ON outbox (created_at) WHERE published_at IS NULL;

Индекс частичный — по «горячей» части (не-опубликованные): выборка воркера всегда быстрая, даже когда в таблице миллион старых записей.

final class PlaceOrderAction
{
    public function handle(array $data): Order
    {
        return DB::transaction(function () use ($data) {
            // 1. Основные данные
            $order = Order::create($data);

            // 2. Событие в outbox — та же транзакция
            DB::table('outbox')->insert([
                'aggregate_type' => 'Order',
                'aggregate_id'   => $order->id,
                'event_type'     => 'OrderCreated',
                'payload'        => json_encode([
                    'order_id' => $order->id,
                    'total'    => $order->total,
                    'items'    => $order->items->toArray(),
                ]),
                'created_at'     => now(),
            ]);

            return $order;
            // COMMIT — обе записи атомарно
        });
    }
}

Обрати внимание: никакого Kafka::publish() внутри транзакции. Публикация — забота отдельного воркера. Даже если Kafka лежит — заказ создан, событие ждёт в БД.

// app/Console/Commands/RelayOutboxCommand.php
final class RelayOutboxCommand extends Command
{
    protected $signature = 'outbox:relay';

    public function handle(KafkaProducer $kafka): int
    {
        while (true) {
            DB::transaction(function () use ($kafka) {
                // SKIP LOCKED — параллельные воркеры не мешают друг другу
                $events = DB::select("
                    SELECT * FROM outbox
                    WHERE published_at IS NULL
                    ORDER BY id
                    LIMIT 100
                    FOR UPDATE SKIP LOCKED
                ");

                foreach ($events as $e) {
                    $kafka->publish($e->event_type, $e->aggregate_id, $e->payload);
                    DB::table('outbox')->where('id', $e->id)
                        ->update(['published_at' => now()]);
                }
            });

            if (empty($events)) sleep(1);   // нечего делать — пауза
        }
    }
}

Запуск: supervisord / systemd держит команду постоянно. Несколько воркеров можно запустить параллельно — SKIP LOCKED гарантирует, что каждое событие возьмёт только один.

• Микросервисы, где надо гарантированно уведомить downstream о доменных событиях.
• Модульные монолиты с eventual consistency между модулями (даже без брокера — тот же паттерн для отложенных Jobs).
• Интеграция с внешними API: платёжный вебхук, отправка в CRM, синхронизация с 1С. Всё, где потеря = деньги/данные.

Когда не нужен: монолит, всё в одной БД, обработка синхронная — просто дёргай event listener напрямую. Для маленьких проектов outbox — оверинжиниринг.

Мультитенантность — архитектура, при которой одно развёрнутое приложение обслуживает несколько независимых клиентов (тенантов), а данные каждого изолированы от остальных. Один код, одна инфраструктура, N клиентов, которые друг о друге не знают.

Типичные примеры: SaaS-сервис, где каждая компания-клиент видит только свои данные; платформа интернет-магазинов, где в одной базе живут десятки брендов; биллинговая система, обслуживающая сотни организаций.

Самая частая путаница: мультитенантность отождествляют с привязкой пользователей к организациям (компания → филиал → отдел). Это два разных слоя, которые решают разные задачи.

Выбор уровня — центральное архитектурное решение. Это компромисс между стоимостью эксплуатации и жёсткостью границы.

На практике тенант и оргструктура сосуществуют: тенант — это клиент, а внутри него разворачивается иерархия подразделений.

CREATE TABLE tenants (
    id          BIGSERIAL PRIMARY KEY,
    name        VARCHAR(255) NOT NULL,
    slug        VARCHAR(64)  NOT NULL UNIQUE   -- поддомен: romashka.app.com
);

CREATE TABLE organizations (
    id          BIGSERIAL PRIMARY KEY,
    tenant_id   BIGINT       NOT NULL REFERENCES tenants(id),
    parent_id   BIGINT       NULL REFERENCES organizations(id),
    type        VARCHAR(32)  NOT NULL,   -- company | branch | department
    name        VARCHAR(255) NOT NULL,
    path        VARCHAR(255) NOT NULL    -- '1/5/12' — materialized path
);

CREATE TABLE organization_user (
    organization_id BIGINT NOT NULL REFERENCES organizations(id),
    user_id         BIGINT NOT NULL REFERENCES users(id),
    role            VARCHAR(32) NOT NULL,
    PRIMARY KEY (organization_id, user_id)
);

-- Уникальность ВСЕГДА в паре с tenant_id
CREATE UNIQUE INDEX users_tenant_email_uniq ON users (tenant_id, email);

Фильтр по тенанту не должен зависеть от памяти разработчика. Он вешается глобальным scope, который применяется ко всем запросам модели.

// app/Models/Concerns/BelongsToTenant.php
trait BelongsToTenant
{
    protected static function bootBelongsToTenant(): void
    {
        // 1. Чтение: любой запрос автоматически сужается до текущего тенанта
        static::addGlobalScope('tenant', function (Builder $q) {
            if ($id = app(TenantContext::class)->id()) {
                $q->where($q->getModel()->qualifyColumn('tenant_id'), $id);
            }
        });

        // 2. Запись: tenant_id проставляется сам, его нельзя забыть
        static::creating(function (Model $model) {
            $model->tenant_id ??= app(TenantContext::class)->id();
        });
    }
}

Контекст тенанта определяется один раз в middleware — по поддомену, заголовку или самому пользователю — и живёт в контейнере на время запроса:

class ResolveTenant
{
    public function handle(Request $request, Closure $next)
    {
        $tenant = Tenant::where('slug', explode('.', $request->getHost())[0])
            ->firstOrFail();

        // Пользователь из другого тенанта не должен сюда попасть
        abort_if(auth()->user()?->tenant_id !== $tenant->id, 403);

        app(TenantContext::class)->set($tenant);

        return $next($request);
    }
}

Здесь всё наоборот: правила пишутся руками и живут в Policy. Типичное требование — «руководитель видит свою орг.единицу и все вложенные». Materialized path (path = '1/5/12') решает это одним LIKE, без рекурсивных запросов.

class ReportPolicy
{
    public function view(User $user, Report $report): bool
    {
        // tenant_id уже отфильтрован global scope'ом — здесь только оргструктура
        return $user->organizations()
            ->where(function ($q) use ($report) {
                // своя единица ИЛИ любой её предок
                $q->whereRaw('? LIKE organizations.path || \'%\'', [$report->organization->path]);
            })
            ->exists();
    }
}

• Мультитенантность — изоляция данных независимых клиентов внутри одного приложения. Это граница безопасности.
• Три уровня изоляции: колонка tenant_id, отдельная схема, отдельная БД. Выбор — компромисс между стоимостью эксплуатации и жёсткостью границы.
• Оргструктура (компания → филиал → отдел) — это не мультитенантность, а модель предметной области с иерархией и авторизацией.
• Изоляция тенанта должна быть неявной (global scope), авторизация внутри тенанта — явной (Policy). Перепутать слои местами означает построить безопасность на том, что кто-то не забудет дописать where.
• Утечки живут не в Eloquent, а по краям: очереди, raw-запросы, кэш, файлы, поисковые индексы.

Дано: 200-строчный UserController, написанный в стиле «всё в одном». Задача — пошагово привести к читаемому и тестируемому виду без изменения поведения.

class UserController extends Controller
{
    public function register(Request $request)
    {
        $data = $request->validate([
            'email' => 'required|email|unique:users',
            'password' => 'required|min:8',
            'country' => 'required|string|size:2',
        ]);

        if (! in_array($data['country'], ['KZ', 'RU', 'US', 'DE'])) {
            return response()->json(['error' => 'Country not supported'], 422);
        }

        $user = User::create([
            'email' => $data['email'],
            'password' => Hash::make($data['password']),
            'country' => $data['country'],
        ]);

        Log::info('user.registered', ['user_id' => $user->id]);

        if ($request->has('promo_code')) {
            $promo = Promo::where('code', $request->input('promo_code'))->first();
            if ($promo && $promo->is_active) {
                $user->update(['credit' => $promo->amount]);
            }
        }

        Mail::to($user->email)->send(new WelcomeMail($user));
        Http::post('https://analytics.example.com/event', ['event' => 'signup']);

        return response()->json($user);
    }
}

// Controller — 5 строк
final class UserController
{
    public function register(RegisterUserRequest $r, RegisterUser $action): JsonResponse
    {
        $user = $action(RegisterUserData::fromRequest($r));
        return response()->json(new UserResource($user), 201);
    }
}

// Action — 12 строк, оркестрация
final class RegisterUser
{
    public function __construct(
        private UserRepository  $users,
        private ApplyPromoCode $promo,
    ) {}

    public function __invoke(RegisterUserData $data): User
    {
        return DB::transaction(function () use ($data) {
            $user = $this->users->create($data);
            if ($data->promoCode) ($this->promo)($user, $data->promoCode);
            UserRegistered::dispatch($user)->afterCommit();
            return $user;
        });
    }
}

Метрики до/после:

• Controller: 200 строк → 6 строк × 6 методов = 36 строк;
• Тестируемость: невозможно (мок 5 фасадов) → легко (DI, фейк-репозитории);
• Добавить новый источник промокодов: правка Controller → новая стратегия в ApplyPromoCode;
• Бизнес-логика отделена от инфраструктуры (mail, analytics — через события).