Modularny monolit w Laravelu: granice przed mikroserwisami

10 min. czytania

Większość aplikacji Laravel zaczyna jako jedna aplikacja, bo właśnie tak powinna zacząć. Jeden deployment, jedna baza, jedna kolejka i jeden debugger ułatwiają zrozumienie nowego produktu oraz obniżają koszt zmian. Kłopoty zaczynają się od przypadkowego monolitu: app/Services staje się szufladą na niepowiązane zachowania, każdy kontroler może odpytać każdy model, a zmiana w rozliczeniach po cichu sięga do realizacji zamówień.

Modularny monolit zachowuje operacyjną prostotę jednej aplikacji Laravel i nadaje granicom biznesowym wyraźną formę w kodzie, dzięki czemu późniejsze wydzielenie serwisu jest możliwe, ale nie wymagane z góry.

Użyjemy aplikacji B2B z katalogiem, zamówieniami, rozliczeniami i fulfilmentem. Ułożymy kod według modułów, wymusimy jeden kierunek zależności, sprawdzimy tę regułę w CI i ustalimy, co faktycznie zasługuje na mały shared kernel.

Zacznij od granicy biznesowej, nie od warstwy technicznej

Znany układ Laravela jest wygodny na początku:

text
app/
  Http/Controllers/
  Models/
  Services/
  Jobs/

Grupuje klasy według roli frameworkowej, a nie powodu zmiany biznesowej. Utworzenie zamówienia może dotykać kontrolera, requestu, modelu, serwisu, zdarzenia i joba w sześciu katalogach. Osoba zmieniająca przepływ zamówienia musi znać całą aplikację, zanim odnajdzie potrzebny kod.

Układ module-first trzyma use case blisko współpracujących z nim elementów:

text
app/
  Modules/
    Catalog/
      Application/
      Domain/
      Infrastructure/
      Http/
    Orders/
      Application/
      Domain/
      Infrastructure/
      Http/
    Billing/
      Application/
      Domain/
      Infrastructure/
  Shared/
    Domain/
    Infrastructure/

Nie traktuj tego jako nakazu czterech warstw wszędzie. Nazwy uwidaczniają dwa pytania: który moduł jest właścicielem tej reguły oraz która zależność przekracza granicę modułu? Modele Eloquent, takie jak Order, trafiają do Infrastructure, bo są adapterami persystencji, a Domain zawiera zdarzenia i reguły biznesowe. Mały moduł może mieć wyłącznie Application i Http; Domain lub Infrastructure dodaj dopiero wtedy, gdy zawiera pojęcie albo adapter, który zyskuje na osobnej granicy.

Nadaj każdemu modułowi publiczną powierzchnię aplikacyjną

Orders jest właścicielem czynności złożenia zamówienia. Kontroler powinien zależeć od tej akcji, nie od Order, Product, StockItem i zdarzenia z trzech innych modułów. Wejście staje się małym, niemutowalnym kontraktem.

php
<?php

declare(strict_types=1);

namespace App\Modules\Orders\Application;

final readonly class PlaceOrderData
{
    /** @param list<PlaceOrderLineData> $lines */
    public function __construct(
        public int $customerId,
        public array $lines,
    ) {
        if ($lines === []) {
            throw new \InvalidArgumentException('An order requires at least one line.');
        }
    }
}

final readonly class PlaceOrderLineData
{
    public function __construct(
        public int $productId,
        public int $quantity,
    ) {
        if ($quantity < 1) {
            throw new \InvalidArgumentException('Quantity must be positive.');
        }
    }
}

Adapter HTTP tłumaczy zwalidowane dane requestu na ten kontrakt. Nie powinien sam stać się przepływem realizacji zamówienia.

php
<?php

declare(strict_types=1);

namespace App\Modules\Orders\Http;

use App\Http\Controllers\Controller;
use App\Modules\Orders\Application\PlaceOrder;
use App\Modules\Orders\Application\PlaceOrderData;
use App\Modules\Orders\Application\PlaceOrderLineData;
use Illuminate\Http\RedirectResponse;

final class PlaceOrderController extends Controller
{
    public function __construct(
        private readonly PlaceOrder $placeOrder,
    ) {}

    public function __invoke(PlaceOrderRequest $request): RedirectResponse
    {
        $validated = $request->validated();

        $order = $this->placeOrder->handle(new PlaceOrderData(
            customerId: $validated['customer_id'],
            lines: array_map(
                fn (array $line): PlaceOrderLineData => new PlaceOrderLineData(
                    productId: $line['product_id'],
                    quantity: $line['quantity'],
                ),
                $validated['lines'],
            ),
        ));

        return to_route('orders.show', $order);
    }
}

Kontroler może leżeć w module, podczas gdy trasy zostają w routes/web.php. Liczy się tylko kierunek zależności; nie trzeba przenosić każdej konwencji Laravela do nowego katalogu.

Zależy od kontraktu innego modułu, nigdy od jego tabel

Orders musi zarezerwować stan magazynowy z Catalogu. Zaimportowanie modelu Eloquent z Catalog kusi, lecz uzależnia przepływ zamówienia od sposobu persystencji katalogu i zachęca do bezpośrednich zmian danych należących do innego modułu. Zamiast tego Catalog publikuje kontrakt aplikacyjny opisujący zdolność potrzebną Orders.

php
<?php

declare(strict_types=1);

namespace App\Modules\Catalog\Application;

interface StockReservation
{
    public function reserve(int $productId, int $quantity, string $reference): void;
}

Akcja Order otrzymuje tę zdolność, jest właścicielem swojej transakcji i publikuje fakt biznesowy po zatwierdzeniu zapisu. Może używać własnych modeli Eloquent, ale nie może sięgać do modeli Catalogu.

php
<?php

declare(strict_types=1);

namespace App\Modules\Orders\Application;

use App\Modules\Catalog\Application\StockReservation;
use App\Modules\Orders\Domain\OrderPlaced;
use App\Modules\Orders\Infrastructure\Order;
use Illuminate\Contracts\Events\Dispatcher;
use Illuminate\Support\Facades\DB;

final class PlaceOrder
{
    public function __construct(
        private readonly StockReservation $stockReservation,
        private readonly Dispatcher $events,
    ) {}

    public function handle(PlaceOrderData $data): Order
    {
        return DB::transaction(function () use ($data): Order {
            $order = Order::query()->create([
                'customer_id' => $data->customerId,
                'status' => 'pending',
            ]);

            foreach ($data->lines as $line) {
                $this->stockReservation->reserve(
                    productId: $line->productId,
                    quantity: $line->quantity,
                    reference: (string) $order->getKey(),
                );

                $order->lines()->create([
                    'product_id' => $line->productId,
                    'quantity' => $line->quantity,
                ]);
            }

            $this->events->dispatch(new OrderPlaced(orderId: $order->getKey()));

            return $order;
        });
    }
}

Na produkcji sama transakcja nie gwarantuje dostarczenia komunikatu asynchronicznemu odbiorcy. Użyj rekordu outbox albo zdarzenia ShouldDispatchAfterCommit, gdy efekt uboczny nie może zobaczyć wycofanego zamówienia. Zdarzenia komunikują zakończony fakt, a bezpośrednie wywołania między modułami tworzą synchroniczną zależność.

php
<?php

declare(strict_types=1);

namespace App\Modules\Orders\Domain;

use Illuminate\Contracts\Events\ShouldDispatchAfterCommit;

final readonly class OrderPlaced implements ShouldDispatchAfterCommit
{
    public function __construct(public int $orderId) {}
}

Billing może teraz nasłuchiwać OrderPlaced i utworzyć fakturę, bez wiedzy Orders o tym, czy faktura istnieje. Nie publikuj zdarzenia wyłącznie po to, aby uniknąć zwykłej wartości zwrotnej: gdy wywołujący potrzebuje odpowiedzi od razu, czytelniejszy jest jawny kontrakt aplikacyjny.

Utrzymuj shared kernel celowo mały

Shared to część, którą większość modularnych monolitów rozwiązuje źle. Zaczyna jako dom dla prawdziwie przekrojowych abstrakcji, a kończy jako app/Shared/Everything. Traktuj go jak kernel z wysokim progiem przyjęcia.

Value object waluty, identyfikator aktora albo ogólny zegar może tam należeć, jeśli kilka modułów rzeczywiście dzieli to samo znaczenie i cykl życia. OrderStatus, CatalogProduct ani InvoiceNumber nie należą: przeniesienie ich do Shared tylko ukrywa właściciela.

php
<?php

declare(strict_types=1);

namespace App\Shared\Domain;

final readonly class Money
{
    public function __construct(
        public int $amountInMinorUnits,
        public string $currency,
    ) {
        if ($amountInMinorUnits < 0) {
            throw new \InvalidArgumentException('Money cannot be negative.');
        }

        if (preg_match('/^[A-Z]{3}$/', $currency) !== 1) {
            throw new \InvalidArgumentException('Currency must be a three-letter ISO code.');
        }
    }
}

Test: czy Catalog, Orders i Billing mogą używać tego obiektu bez czekania jednego modułu na zmianę biznesową drugiego? Jeśli nie, zduplikuj mały typ lokalnie. Odrobina duplikacji jest tańsza niż fałszywa wspólna zależność.

Zamień granicę w wykonywalną regułę

Nazwy katalogów są konwencją. Konwencja bez testu staje się opcjonalna podczas napiętego wydania. Deptrac potrafi sprawdzić warstwy architektury i dostęp modułów w CI. Dokładna konfiguracja powinna odpowiadać namespace'om projektu; ta wersja pokazuje ważną zasadę: moduł może używać siebie, Shared i opublikowanych kontraktów innego modułu, ale nie jego kodu Infrastructure ani Http. W tym przykładzie Catalog\Application zawiera wyłącznie opublikowane kontrakty, więc dostaje własną warstwę.

yaml
deptrac:
  paths:
    - ./app
  layers:
    - name: Orders
      collectors:
        - type: directory
          value: app/Modules/Orders/.*
    - name: CatalogContracts
      collectors:
        - type: directory
          value: app/Modules/Catalog/Application/.*
    - name: Catalog
      collectors:
        - type: bool
          must:
            - type: directory
              value: app/Modules/Catalog/.*
          must_not:
            - type: directory
              value: app/Modules/Catalog/Application/.*
    - name: Shared
      collectors:
        - type: directory
          value: app/Shared/.*
    - name: Laravel
      collectors:
        - type: classLike
          value: Illuminate\\.*
  ruleset:
    Orders:
      - CatalogContracts
      - Shared
      - Laravel
    Catalog:
      - CatalogContracts
      - Shared
      - Laravel
    CatalogContracts:
      - Shared
      - Laravel
    Shared:
      - Laravel

Orders może używać CatalogContracts, ale nie Catalog, więc import StockReservation przechodzi, a użycie modeli Eloquent albo kontrolerów Catalogu przerywa build. Kolektor bool wyłącza kontrakty z warstwy Catalog; bez must_not ta sama klasa należałaby do obu warstw i nadal byłaby zgłaszana względem ostrzejszej. Nie osłabiaj każdej granicy tylko po to, aby przepuścić jedną zależność.

Testy architektury PHP są kolejną przydatną linią obrony, ponieważ uruchamiają się z zestawem testów i kończą znajomym komunikatem.

php
<?php

declare(strict_types=1);

arch('orders do not use catalog infrastructure')
    ->expect('App\\Modules\\Orders')
    ->not->toUse('App\\Modules\\Catalog\\Infrastructure');

arch('other modules do not use the catalog HTTP layer')
    ->expect('App\\Modules\\Orders')
    ->not->toUse('App\\Modules\\Catalog\\Http');

arch('billing does not use the catalog HTTP layer')
    ->expect('App\\Modules\\Billing')
    ->not->toUse('App\\Modules\\Catalog\\Http');

Każda reguła wskazuje moduł, którego kod sprawdza, dlatego własne klasy HTTP Catalogu nie są zgłaszane za używanie siebie nawzajem. Żadne z tych narzędzi nie ocenia projektu; sprawdzają tylko uzgodniony projekt przy każdym buildzie. Zacznij od dwóch lub trzech reguł o największej wartości i zaostrzaj je wraz z usuwaniem starych naruszeń; tysiąc ignorowanych wyjątków jest gorszy niż brak reguły.

Testuj zachowanie na granicy modułu

Publiczna akcja jest naturalnym miejscem dla testu feature. Test powinien potwierdzać wynik biznesowy i współpracę modułów, a nie prywatne wywołania metod.

php
<?php

declare(strict_types=1);

use App\Models\Customer;
use App\Modules\Catalog\Application\StockReservation;
use App\Modules\Catalog\Infrastructure\Product;
use App\Modules\Orders\Application\PlaceOrder;
use App\Modules\Orders\Application\PlaceOrderData;
use App\Modules\Orders\Application\PlaceOrderLineData;
use App\Modules\Orders\Domain\OrderPlaced;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Event;

uses(RefreshDatabase::class);

final class FakeStockReservation implements StockReservation
{
    /** @var list<array{productId: int, quantity: int, reference: string}> */
    public array $reservations = [];

    public function reserve(int $productId, int $quantity, string $reference): void
    {
        $this->reservations[] = compact('productId', 'quantity', 'reference');
    }
}

it('places an order after catalog reserves stock', function (): void {
    $customer = Customer::factory()->create();
    $product = Product::factory()->create();

    Event::fake([OrderPlaced::class]);

    $reservation = new FakeStockReservation();
    app()->instance(StockReservation::class, $reservation);

    $order = app(PlaceOrder::class)->handle(new PlaceOrderData(
        customerId: $customer->id,
        lines: [new PlaceOrderLineData(productId: $product->id, quantity: 2)],
    ));

    expect($order->status)->toBe('pending');
    expect($reservation->reservations)->toHaveCount(1);
    Event::assertDispatched(
        OrderPlaced::class,
        fn (OrderPlaced $event): bool => $event->orderId === $order->id,
    );
});

Fake izoluje jedną zewnętrzną zdolność (rezerwację stanu), a zapis zamówienia pozostaje prawdziwy. Factories tworzą klienta i produkt przed Event::fake(), zgodnie z zaleceniem dokumentacji Laravela, a fałszowanie samego OrderPlaced nie rusza zdarzeń modeli Eloquent. Testy kontraktowe opublikowanego interfejsu się opłacają, gdy jego implementacja stanie się zdalna.

Kiedy modularny monolit jest lepszym wyborem

Wybierz tę architekturę, gdy produkt nadal jest jednym systemem biznesowym, ten sam zespół wydaje jego części razem, a zmiany między modułami są częste. Zyskujesz lokalne rozumienie kodu, własność i testowalne granice bez powielania uwierzytelniania, deploymentów, obserwowalności, kolejek i mechanizmów spójności danych w wielu serwisach.

Moduły mogą dzielić framework, kontener i transakcję bazodanową, ale drzewo źródeł przestaje udawać, że każdy model należy do wszystkich.

Kiedy NIE używać tego podejścia

Nie narzucaj warstw modułowych małej aplikacji CRUD z trzema ekranami i jednym pojęciem biznesowym. Czytelne app/Models, Form Request i kontroler mogą być tańszym projektem. Nie twórz modułu na każdy model Eloquent i nie wprowadzaj zdarzenia dla każdego settera. Granice powinny wynikać ze zmian biznesowych oraz własności, nie z liczby tabel.

Nie nazywaj też systemu modularnym monolitem, jeśli wszystkie moduły mogą odpytywać swoje tabele nawzajem. To tylko przeorganizowana duża kula błota. Zacznij od miejsc, w których przypadkowe powiązanie już powoduje poprawki: Billing zmieniający status Order, raportowanie przechodzące przez pięć relacji lub integracja czyniąca kod kontrolera trudnym do testowania.

Kiedy naprawdę wydzielić serwis

Katalog nie jest mikroserwisem czekającym na klaster Kubernetes. Wydzielaj dopiero wtedy, gdy za granicą stoją dowody operacyjne: inny zespół musi wdrażać niezależnie, obciążenie wymaga osobnego skalowania lub izolacji, reguły regulacyjne wymagają osobnej kontroli danych albo profil awarii jest istotnie inny.

Przed ekstrakcją udowodnij granicę wewnątrz monolitu. Nadaj jej kontrakt, zablokuj skróty do bazy danych, obsługuj zdarzenia idempotentnie i obserwuj wywołania. Pierwsze wydzielenie zastępuje wtedy adapter in-process przez HTTP, kolejkę lub integrację z właścicielem danych, a nie każdą klasę wywołaniem sieciowym.

Koszt jest realny: distributed tracing, retry, idempotencja, ewolucja schematów, lokalny development i obsługa incydentów stają się trudniejsze. Modularny monolit wygrywa, gdy odracza ten koszt, aż biznes rzeczywiście na niego zasłuży.

Typowe pułapki

Najczęstsza pułapka to ogromny katalog Shared. Niech własność pozostanie widoczna; promuj typ dopiero po wielokrotnym, stabilnym użyciu między modułami. Druga to synchroniczny teatr zdarzeń: publikowanie eventu i natychmiastowe poleganie na listenerze dla poprawności czyni przepływ niewidocznym. Użyj bezpośredniego kontraktu dla synchronicznych decyzji, a zdarzeń dla zakończonych faktów.

Kolejnym błędem jest traktowanie wyjątków Deptraca jako niegroźnych. Każde ignorowane naruszenie dokumentuje niejasną zależność. Utwórz wąski publiczny kontrakt albo tymczasowo usuń regułę; nie buduj długu baseline, którego nikt nie czyta. Pamiętaj wreszcie, że jedna transakcja bazodanowa to wygoda, nie granica architektoniczna. Gdy przyszły serwis będzie właścicielem danych, jego kontrakt i tryby awarii muszą być już jawne.

Powiązane artykuły

Wsparcie istniejącego systemu

Potrzebujesz pomocy z działającą aplikacją?

Pomagam firmom rozwijać działające systemy, porządkować wdrożenia i dodawać nowe funkcje bez dokładania chaosu do projektu.

Komentarze (0)
Zaloguj się, aby dodać komentarz

Musisz być zalogowany, aby dodać komentarz.

Zaloguj się

Potrzebujesz kogoś, kto weźmie odpowiedzialność za kolejny krok?

Porozmawiajmy o Twoim projekcie i określmy zakres, który ma sens dla Twoich celów.