Modelli eloquenti troppo grandi

Eloquent è uno dei pezzi più produttivi di Laravel. Ti consente di modellare relazioni, interrogare dati ed esprimere parte del comportamento del dominio in modo molto comodo. Questa comodità è proprio ciò che fa sì che molti progetti inizino a lasciare ogni nuova regola all’interno del modello.

All'inizio sembra una buona decisione: il codice è vicino ai dati e tutto si muove velocemente. Il problema sorge quando il modello smette di rappresentare un'entità e inizia a coordinare processi completi. A quel punto, modificare una regola aziendale, una risposta API o una query critica può comportare il tocco di una classe che concentra già troppe ragioni per cambiare.

Un modello grande non è male solo perché ha tante linee. È preoccupante quando si mescolano tenacia, business, presentazione, contesto HTTP e coordinamento degli effetti collaterali. Questa miscela confonde il confine tra “cos’è questa entità” e “cosa fa il sistema quando succede qualcosa con questa entità”.

Un primo segnale è trovare metodi lunghi che non descrivano il comportamento naturale del modello. Ad esempio, metodi che preparano una risposta completa per un endpoint, calcolano decisioni aziendali con molte condizioni o coordinano più modelli esterni. Il nome può sembrare innocuo, ma il contenuto non appartiene più all'entità.

Vale anche la pena dare un'occhiata agli ambiti. Un ambito piccolo ed espressivo può essere utile. Un insieme di ambiti che accumula filtri condizionali, dipendenze utente, regole di visibilità, ordinamento dei prodotti e logica delle autorizzazioni inizia a comportarsi come un oggetto query nascosto all'interno del modello.

Altri segni comuni sono accessori e mutatori che risolvono decisioni sul prodotto, dipendenza indiretta da richiesta, autenticazione, sessione o configurazione, risposte API preparate all'interno del modello, regole aziendali mescolate con persistenza e test che possono essere coperti solo creando troppo contesto attorno ad essi.

Laravel ti consente di andare avanti rapidamente e questo è un vero vantaggio. In una prima versione, avvicinare la logica a Eloquent può ridurre l'attrito e aiutare a convalidare il prodotto. Il problema non è partire in modo semplice, ma non rivedere i limiti quando il sistema cambia scala.

Molti progetti passano dal semplice CRUD al prodotto di produzione senza un livello applicativo chiaro. Quando viene visualizzata una nuova regola, il modello sembra il luogo naturale in cui eliminarla poiché dispone già di relazioni, attributi e accesso al database. Se tale decisione viene ripetuta per mesi, il modello finisce per fungere da servizio, livello di query, trasformatore e politica allo stesso tempo.

Non è un bug di Laravel. È una conseguenza normale della crescita con pressione di consegna e senza una revisione tecnica periodica. Proprio per questo è importante individuare il disegno prima che il modello diventi un pezzo che nessuno vuole toccare.

Il rischio più visibile è la lentezza. Ogni cambiamento richiede la comprensione di più contesto del necessario perché la classe non ha più una responsabilità chiara. Una modifica a una regola aziendale può influire su una query, una trasformazione API o un'operazione asincrona che si trova nello stesso file.

Appare anche la paura di toccare il codice. Quando un modello concentra troppa logica, il team smette di fare affidamento su piccoli cambiamenti. I test sono più difficili da scrivere perché ogni metodo porta con sé persistenza, relazioni, fabbriche e stati secondari. Anche l'ottimizzazione delle query diventa più complessa perché la query è mescolata con decisioni aziendali.

Nel medio termine, questo modello genera un accoppiamento tra il modello API e le regole del prodotto. Il riutilizzo della logica in un nuovo comando, lavoro o endpoint costringe a caricare più dipendenze del necessario. Il debito tecnico tace perché l'applicazione può continuare a funzionare, ma ogni iterazione costa di più.

Il primo criterio è preservare nel modello il comportamento essenziale dell'entità: relazioni, cast, attributi rilevanti, piccole regole specifiche dello stato e metodi che descrivono realmente qualcosa che il modello “è” o “conosce”. Se il metodo coordina un processo, probabilmente appartiene ad un altro livello.

I casi d'uso possono essere estratti in Servizi o Azioni. Le query complesse possono risiedere in oggetti query, ambiti più piccoli o classi specifiche. La convalida HTTP deve essere presente nelle richieste del modulo. La trasformazione di output si adatta meglio alle risorse API. L'autorizzazione deve essere delegata alle Politiche o ai Cancelli. I processi pesanti o differiti di solito appartengono a Jobs.

Non è necessario creare un’enorme architettura tutta in una volta. È più sensato iniziare con le aree che presentano maggiori cambiamenti, maggiori bug o maggiori rischi. Un'estrazione ben scelta riduce immediatamente l'attrito; un'estrazione per l'estetica può aggiungere complessità senza migliorare la capacità di evoluzione.

Immagina un modello di ordine che calcola lo stato della negoziazione, prepara il payload API, applica filtri avanzati, controlla le autorizzazioni e attiva notifiche. Niente di tutto ciò interrompe necessariamente la produzione, ma trasforma Order in un pezzo con troppe responsabilità.

Una separazione più chiara potrebbe lasciare all’Ordine relazioni, attributi e comportamenti essenziali. CreateOrderAction o OrderService gestiranno il caso d'uso. OrderQuery risolverebbe filtri complessi. OrderResource trasformerebbe l'output in API. OrderPolicy deciderebbe le autorizzazioni. Un lavoro gestirebbe notifiche o processi pesanti.

Il miglioramento non è “avere più classi”. Il miglioramento è che ogni cambiamento futuro ha un posto più evidente. Se cambi la risposta da API, non tocchi il modello. Se l'autorizzazione cambia, non toccare la query. Se il processo di creazione cambia, non mescoli quella decisione con la presentazione.

Prima di accettare un altro metodo all'interno del modello, vale la pena chiedersi: rappresenta il comportamento dell'entità o coordina un caso d'uso? Dipende da HTTP, richiesta, autenticazione, sessione o contesto esterno? Stai preparando una risposta per il frontend o API? Contiene una query complessa difficile da riutilizzare?

È anche utile verificare se si combinano regole aziendali con persistenza, se sarebbe più chiaro come azione, servizio, oggetto query, risorsa o politica e se può essere testato senza creare troppo stato attorno ad esso. Se la risposta a più domande è negativa, probabilmente il modello sta assorbendo responsabilità che dovrebbero essere separate.

Un modello di grandi dimensioni non sempre interrompe l'applicazione, ma solitamente indica che l'architettura sta perdendo i suoi limiti. Il segnale importante non è il numero esatto di righe, ma il numero di decisioni diverse che coesistono nella stessa classe.

Se il tuo Laravel funziona, ma ogni modifica inizia a toccare troppi pezzi, un audit di backend Laravel può aiutarti a rilevare quali responsabilità dovrebbero essere separate per prime e quali vittorie rapide hanno l'impatto più reale.