Jak strukturalizować serwis/architekturę dla dużej aplikacji Laravel?

Question

Accepted Answer

W miarę wzrostu aplikacji Laravel domyślne podejście "gruby kontroler / gruby model" staje się trudne do utrzymania. Większe aplikacje czerpią korzyści z **dodatkowych warstw architektonicznych** — klas serwisów, klas akcji, repozytoriów, form requests i jasnej organizacji domeny — aby zachować logikę biznesową zorganizowaną, testowalną i łatwą w utrzymaniu.

## Problem: logika trafia w złe miejsca

```text
Small apps: logic in controllers and models is fine.
Large apps: controllers get bloated, models become "god objects", logic is duplicated
→ hard to test, maintain, and reason about. Extract logic into dedicated layers.
```

## Klasy serwisów — kapsułkowanie logiki biznesowej

```php
<?php
// move complex business logic out of controllers into a service
class OrderService {
    public function __construct(
        private PaymentGateway $payments,
        private InventoryService $inventory,
    ) {}

public function placeOrder(User $user, array $items): Order {
        // orchestrate the business process — reusable, testable, focused
        DB::transaction(function () use ($user, $items) { /* ... */ });
    }
}

// the controller stays THIN — just delegates
public function store(StoreOrderRequest $request, OrderService $orders) {
    return $orders->placeOrder($request->user(), $request->validated());
}
```

**Klasy serwisów** zawierają logikę biznesową, utrzymując kontrolery szczupłe (zajmujące się tylko HTTP) i modele skoncentrowane na danych — a logika staje się wielokrotnie użyteczna i niezależnie testowalna.

## Inne przydatne wzorce dla dużych aplikacji

```text
✓ Action classes — a single class per use-case (e.g. CreateUserAction) — very focused
✓ Form Requests — extract validation + authorization out of controllers
✓ API Resources — control response shape, separate from models
✓ Repository pattern — abstract data access behind interfaces (when you need it;
  often Eloquent suffices, so don't add it reflexively)
✓ Events/listeners — decouple side effects from core logic
✓ Domain-oriented organization — group code by feature/domain, not just by type
  (e.g. a modules/ structure) as the app grows
✓ Dependency injection + interfaces — for loose coupling and testability
```

## Wytyczne kierunkowe

```text
✓ Thin controllers (HTTP only) → services/actions (business logic) → models (data)
✓ Single Responsibility — each class does one thing
✓ Depend on abstractions (interfaces) for testability and flexibility
✗ Don't over-engineer — add layers when complexity justifies them, not prematurely
```

## Dlaczego to ważne

Zrozumienie sposobu strukturalizacji dużej aplikacji Laravel to ważna wiedza na poziomie senior, ponieważ konwencje, które sprawdzają się dla małych aplikacji (logika w kontrolerach i modelach), ulegają rozpadowi w dużej skali — prowadząc do rozdętych kontrolerów, "bogów" modeli, zduplikowanej logiki i kodu, który trudno jest testować i utrzymywać.

Znajomość dodatkowych warstw architektonicznych — szczególnie **klas serwisów** (kapsułkowanie logiki biznesowej, aby utrzymać kontrolery szczupłe i modele skoncentrowane, jednocześnie czyniąc logikę wielokrotnie użyteczną i testowalną), plus klasy akcji, Form Requests (ekstrakcja walidacji/autoryzacji), API Resources (kontrolowanie wyniku), wzorzec repozytorium (abstrakcja dostępu do danych, gdy jest to konieczne), zdarzenia (rozdzielanie efektów ubocznych) i **organizacja zorientowana na domenę** (grupowanie po funkcjach w miarę wzrostu aplikacji) — to co pozwala budować aplikacje łatwe w utrzymaniu i skalowalne.

Wytyczne kierunkowe mają znaczenie: **warstwa kontrolery → serwisy → modele**, zasada jednej odpowiedzialności i poleganie na abstrakcjach (interfejsy) dla testowania i słabego sprzężenia.

Równie ważne jest sądzenie, aby **nie przeciążać inżynierią** — dodawać warstwy, gdy złożoność rzeczywiście to uzasadnia, a nie przedwcześnie (domyślne ustawienia Laravel są w porządku dla prostszych aplikacji, a odruchowe dodawanie repozytoriów/abstrakcji wprowadza niepotrzebną złożoność).

Zrozumienie tych wzorców architektonicznych i zasad (oraz powściągliwości) ich stosowania jest cenne do budowania dużych, długowiecznych aplikacji Laravel, które pozostają łatwe w utrzymaniu, testowalne i zrozumiałe w miarę wzrostu — różniąc programistów, którzy potrafią projektować aplikacje skalowalne, od tych, których rosnące aplikacje zapadają się w splątany, trudny do utrzymania kod.

To architektoniczne sądzenie jest cechą zaawansowanego rozwoju Laravel i częstym zagadnieniem dla poważnych, rozwijających się aplikacji.