Modèles éloquents trop grands

Eloquent est l'un des éléments les plus productifs de Laravel. Il permet de modéliser des relations, d'interroger des données et d'exprimer une partie du comportement du domaine de manière très confortable. Ce confort est précisément ce qui pousse de nombreux projets à laisser chaque nouvelle règle au sein du modèle.

Au début, cela semble être une bonne décision : le code est proche des données et tout avance vite. Le problème survient lorsque le modèle cesse de représenter une entité et commence à coordonner des processus complets. À ce stade, modifier une règle métier, une réponse API ou une requête critique peut impliquer de toucher à une classe qui concentre déjà trop de raisons de changer.

Un grand modèle n’est pas mauvais simplement parce qu’il comporte de nombreuses lignes. Il est inquiétant de mélanger persévérance, business, présentation, contexte HTTP et coordination des effets secondaires. Ce mélange brouille la frontière entre « ce qu’est cette entité » et « ce que fait le système lorsque quelque chose arrive à cette entité ».

Un premier signe est de trouver des méthodes longues qui ne décrivent pas le comportement naturel du modèle. Par exemple, les méthodes qui préparent une réponse complète pour un point de terminaison, calculent des décisions commerciales avec de nombreuses conditions ou coordonnent plusieurs modèles externes. Le nom peut paraître innocent, mais le contenu n’appartient plus à l’entité.

Cela vaut également la peine de regarder les étendues. Une petite portée expressive peut être utile. Un ensemble de portées qui accumule les filtres conditionnels, les dépendances des utilisateurs, les règles de visibilité, l'ordre des produits et la logique des autorisations commence à se comporter comme un objet de requête caché dans le modèle.

D'autres signes courants sont les accesseurs et les mutateurs qui résolvent les décisions relatives au produit, la dépendance indirecte à la demande, à l'authentification, à la session ou à la configuration, les réponses API préparées dans le modèle, les règles métier mélangées à la persistance et les tests qui ne peuvent être couverts qu'en créant trop de contexte autour d'eux.

Laravel permet d'avancer rapidement et c'est un réel avantage. Dans une première version, rapprocher la logique d'Eloquent peut réduire les frictions et aider à valider le produit. Le problème n’est pas de démarrer simplement, mais de ne pas revoir les limites lorsque le système change d’échelle.

De nombreux projets vont du simple CRUD au produit de production sans couche d'application claire. Lorsqu'une nouvelle règle apparaît, le modèle semble être l'endroit naturel pour la supprimer car il possède déjà des relations, des attributs et un accès à la base de données. Si cette décision est répétée pendant des mois, le modèle finit par agir à la fois comme un service, une couche de requête, un transformateur et une politique.

Ce n'est pas un bug de Laravel. C'est une conséquence normale d'une croissance avec la pression de livraison et sans examen technique périodique. C'est précisément pour cette raison qu'il est important de détecter le motif avant que le modèle ne devienne une pièce à laquelle personne ne veut toucher.

Le risque le plus visible est la lenteur. Chaque changement nécessite de comprendre plus de contexte que nécessaire car la classe n'a plus de responsabilité claire. Un ajustement d'une règle métier peut affecter une requête, une transformation API ou une opération asynchrone qui réside dans le même fichier.

La peur de toucher au code apparaît également. Lorsqu’un modèle concentre trop de logique, l’équipe cesse de s’appuyer sur de petits changements. Les tests sont plus difficiles à écrire car chaque méthode comporte de la persistance, des relations, des usines et des états secondaires. Même l'optimisation des requêtes devient plus complexe car la requête est mélangée à des décisions commerciales.

À moyen terme, ce modèle génère un couplage entre le modèle, API et les règles du produit. La réutilisation de la logique dans une nouvelle commande, tâche ou point de terminaison vous oblige à charger plus de dépendances que nécessaire. La dette technique est silencieuse car l'application peut continuer à fonctionner, mais chaque itération coûte plus cher.

Le premier critère est de conserver dans le modèle le comportement essentiel de l'entité : relations, casts, attributs pertinents, petites règles spécifiques à l'état et méthodes qui décrivent réellement quelque chose que le modèle « est » ou « sait ». Si la méthode coordonne un processus, elle appartient probablement à une autre couche.

Les cas d'utilisation peuvent être extraits vers des services ou des actions. Les requêtes complexes peuvent résider dans des objets de requête, des étendues plus petites ou des classes spécifiques. La validation HTTP doit se trouver dans les demandes de formulaire. La transformation de sortie correspond le mieux aux ressources API. L'autorisation doit être déléguée aux politiques ou aux portes. Les processus lourds ou différés appartiennent généralement aux Jobs.

Il n’est pas nécessaire de créer une immense architecture d’un seul coup. Il est plus logique de commencer par les domaines présentant le plus de changements, le plus de bugs ou le plus de risques. Une extraction bien choisie réduit immédiatement les frottements ; une extraction pour l’esthétique peut ajouter de la complexité sans améliorer la capacité d’évolution.

Imaginez un modèle d'ordre qui calcule l'état des transactions, prépare la charge utile API, applique des filtres avancés, vérifie les autorisations et déclenche des notifications. Rien de tout cela ne interrompt nécessairement la production, mais cela transforme Order en une pièce avec trop de responsabilités.

Une séparation plus claire pourrait laisser à l’Ordre des relations, des attributs et un comportement essentiels. CreateOrderAction ou OrderService gérerait le cas d'utilisation. OrderQuery résoudrait des filtres complexes. OrderResource transformerait la sortie en API. OrderPolicy déciderait des autorisations. Un Job gérerait les notifications ou les processus lourds.

L'amélioration ne consiste pas à « avoir plus de cours ». L’amélioration est que chaque changement futur a une place plus évidente. Si vous modifiez la réponse de API, vous ne touchez pas le modèle. Si l'autorisation change, vous ne touchez pas à la requête. Si le processus de création change, vous ne mélangez pas cette décision avec la présentation.

Avant d'accepter une autre méthode au sein du modèle, il convient de se demander : représente-t-elle le comportement propre de l'entité ou coordonne-t-elle un cas d'utilisation ? Cela dépend-il de HTTP, de la requête, de l'authentification, de la session ou du contexte externe ? Préparez-vous une réponse pour le frontend ou API ? Contient-il une requête complexe et difficile à réutiliser ?

Cela permet également de vérifier si vous mélangez des règles métier avec la persistance, si cela serait plus clair en tant qu'action, service, objet de requête, ressource ou politique, et s'il peut être testé sans créer trop d'état autour de lui. Si la réponse à plusieurs questions est négative, le modèle absorbe probablement des responsabilités qui devraient être séparées.

Un modèle volumineux ne casse pas toujours l'application, mais cela indique généralement que l'architecture perd ses limites. Le signal important n’est pas le nombre exact de lignes, mais le nombre de décisions différentes qui coexistent dans la même classe.

Si votre Laravel fonctionne, mais que chaque changement commence à toucher trop de pièces, un audit backend Laravel peut vous aider à détecter quelles responsabilités doivent être séparées en premier et quels gains rapides ont l'impact le plus réel.