Como você estrutura um serviço/arquitetura para uma grande aplicação Laravel?

Question

Accepted Answer

Conforme uma aplicação Laravel cresce, a abordagem padrão de "controller gordo / model gordo" se torna difícil de manter. Aplicações maiores se beneficiam de **camadas arquitetônicas adicionais** — classes de serviço, classes de ação, repositórios, form requests e organização clara de domínio — para manter a lógica de negócio organizada, testável e sustentável.

## O problema: a lógica acaba nos lugares errados

```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.
```

## Service classes — encapsular a lógica de negócio

```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());
}
```

**Service classes** contêm a lógica de negócio, mantendo controllers finos (apenas manipulando HTTP) e models focados em dados — e tornando a lógica reutilizável e independentemente testável.

## Outros padrões úteis para grandes aplicações

```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
```

## Os princípios orientadores

```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
```

## Por que isso importa

Entender como estruturar uma grande aplicação Laravel é conhecimento importante de nível sênior, porque as convenções que funcionam para aplicações pequenas (lógica em controllers e models) se desfazem em escala — levando a controllers inchados, models "deus", lógica duplicada e código difícil de testar e manter.

Conhecer as camadas arquitetônicas adicionais — especialmente **service classes** (encapsulando a lógica de negócio para manter controllers finos e models focados, enquanto torna a lógica reutilizável e testável), além de action classes, Form Requests (extraindo validação/autorização), API Resources (controlando saída), o padrão repository (abstraindo acesso a dados quando necessário), events (desacoplando efeitos colaterais) e **organização orientada a domínio** (agrupando por feature conforme a aplicação cresce) — é o que permite construir aplicações sustentáveis e escaláveis.

Os princípios orientadores importam: camadas de **controllers finos → services → models**, responsabilidade única e dependência de abstrações (interfaces) para testabilidade e acoplamento fraco.

Igualmente importante é o julgamento de **não sobre-engenheirar** — adicionando camadas quando a complexidade genuinamente as justifica em vez de prematuramente (os padrões padrão do Laravel são bons para aplicações mais simples, e adicionar reflexivamente repositories/abstrações agrega complexidade desnecessária).

Entender esses padrões arquitetônicos e os princípios (e moderação) para aplicá-los é valioso para construir grandes aplicações Laravel duradouras que permaneçam sustentáveis, testáveis e compreensíveis conforme crescem — distinguindo desenvolvedores que podem arquitetar aplicações escaláveis daqueles cujas aplicações em crescimento desabam em código emaranhado e difícil de manter.

Esse julgamento arquitetônico é uma marca registrada do desenvolvimento Laravel sênior e uma preocupação frequentemente relevante para aplicações sérias e em crescimento.