Modelos eloquentes muito grandes

Eloquent é uma das peças mais produtivas do Laravel. Permite modelar relações, consultar dados e expressar parte do comportamento do domínio de uma forma muito confortável. Este conforto é precisamente o que faz com que muitos projetos comecem a sair de cada nova regra dentro do modelo.

À partida parece uma boa decisão: o código fica próximo dos dados e tudo se move rapidamente. O problema surge quando o modelo deixa de representar uma entidade e passa a coordenar processos completos. Neste ponto, alterar uma regra de negócio, uma resposta API ou uma consulta crítica pode envolver tocar numa classe que já concentra muitos motivos para mudar.

Um modelo grande não é mau só porque tem muitas linhas. É preocupante quando se mistura persistência, negócio, apresentação, contexto HTTP e coordenação de efeitos secundários. Esta mistura esbate a fronteira entre “o que é esta entidade” e “o que o sistema faz quando algo acontece a esta entidade”.

Um primeiro sinal é encontrar métodos longos que não descrevam o comportamento natural do modelo. Por exemplo, métodos que preparam uma resposta completa para um endpoint, calculam decisões de negócio com muitas condições ou coordenam vários modelos externos. O nome pode parecer inocente, mas o conteúdo já não pertence à entidade.

Também vale a pena dar uma vista de olhos aos escopos. Um âmbito pequeno e expressivo pode ser útil. Um conjunto de escopos que acumula filtros condicionais, dependências de utilizadores, regras de visibilidade, ordenação de produtos e lógica de permissões começa a comportar-se como um Objeto de Consulta oculto dentro do modelo.

Outros sinais comuns são accessors e modificadores que resolvem decisões de produto, dependência indirecta de Request, Auth, sessão ou configuração, respostas API preparadas dentro do modelo, regras de negócio misturadas com persistência e testes que só podem ser cobertos criando muito contexto em torno das mesmas.

Laravel permite-lhe avançar rapidamente e isso é uma verdadeira vantagem. Numa primeira versão, aproximar a lógica do Eloquent pode reduzir o atrito e ajudar a validar o produto. O problema não está em começar de forma simples, mas sim em não rever os limites quando o sistema muda de escala.

Muitos projetos vão desde o simples CRUD ao produto de produção sem uma camada de aplicação clara. Quando surge uma nova regra, o modelo parece ser o local natural para a abandonar porque já tem relações, atributos e acesso à base de dados. Se esta decisão se repetir durante meses, o modelo acaba por atuar como serviço, camada de consulta, transformador e política ao mesmo tempo.

Não é um bug do Laravel. É uma consequência normal de crescer com pressão de entrega e sem revisão técnica periódica. Precisamente por isso é importante detetar o padrão antes que o modelo se torne uma peça que ninguém queira tocar.

O risco mais visível é a lentidão. Cada mudança requer a compreensão de mais contexto do que o necessário porque a turma já não tem uma responsabilidade clara. Um ajuste numa regra de negócio pode afetar uma consulta, uma transformação API ou uma operação assíncrona que reside no mesmo ficheiro.

O medo de tocar no código também aparece. Quando um modelo concentra demasiada lógica, a equipa deixa de depender de pequenas mudanças. Os testes são mais difíceis de escrever porque cada método transporta persistência, relações, fábricas e estados secundários. Até a otimização de consultas se torna mais complexa porque a consulta está misturada com decisões de negócio.

A médio prazo, este padrão gera acoplamento entre o modelo, API e as regras do produto. A reutilização da lógica num novo comando, trabalho ou endpoint obriga-o a carregar mais dependências do que o necessário. A dívida técnica é silenciosa porque a aplicação pode continuar a funcionar, mas cada iteração custa mais.

O primeiro critério é preservar no modelo o comportamento essencial da entidade: relações, elencos, atributos relevantes, pequenas regras específicas do estado e métodos que realmente descrevam algo que o modelo “é” ou “sabe”. Se o método coordena um processo, provavelmente pertence a outra camada.

Os casos de utilização podem ser extraídos para Serviços ou Ações. As consultas complexas podem residir em objetos de consulta, escopos mais pequenos ou classes específicas. A validação HTTP terá de estar no Form Requests. A transformação de saída adapta-se melhor às características API. A autorização deve ser delegada em Políticas ou Portões. Os processos pesados ​​ou adiados pertencem geralmente a Jobs.

Não há necessidade de criar uma arquitetura enorme de uma só vez. Faz mais sentido começar pelas áreas com mais alterações, mais bugs ou mais riscos. Uma extração bem escolhida reduz imediatamente o atrito; uma extração para estética pode acrescentar complexidade sem melhorar a capacidade de evolução.

Imagine um modelo de encomenda que calcula o estado de negociação, prepara a carga útil API, aplica filtros avançados, verifica permissões e aciona notificações. Nada disto interrompe necessariamente a produção, mas transforma a Ordem numa peça com muitas responsabilidades.

Uma separação mais clara poderia deixar a Ordem com relações, atributos e comportamentos essenciais. CreateOrderAction ou OrderService tratariam do caso de uso. OrderQuery resolveria filtros complexos. O OrderResource transformaria a saída em API. O OrderPolicy decidiria as permissões. Um Job geriria notificações ou processos pesados.

Melhorar não é “ter mais aulas”. A melhoria é que cada mudança futura tem um lugar mais óbvio. Se alterar a resposta de API, não toca no modelo. Se a autorização for alterada, não toca na consulta. Se o processo de criação mudar, não mistura essa decisão com a apresentação.

Antes de aceitar outro método dentro do modelo, vale a pena perguntar: representa o comportamento da própria entidade ou coordena um caso de uso? Depende de HTTP, pedido, autenticação, sessão ou contexto externo? Está a preparar uma resposta para frontend ou API? Contém uma consulta complexa que é difícil de reutilizar?

Também ajuda verificar se mistura regras de negócio com persistência, se seria mais claro como Ação, Serviço, Objeto de Consulta, Recurso ou Política e se pode ser testado sem construir muito estado à sua volta. Se a resposta a diversas questões for negativa, o modelo está provavelmente a absorver responsabilidades que deveriam ser separadas.

Um modelo grande nem sempre quebra a aplicação, mas geralmente indica que a arquitetura está a perder os seus limites. O sinal importante não é o número exato de linhas, mas o número de decisões diferentes que coexistem na mesma classe.

Se o seu Laravel funcionar, mas cada alteração começar a afetar muitas peças, uma auditoria de back-end Laravel pode ajudá-lo a detetar quais as responsabilidades que devem ser separadas em primeiro lugar e quais os ganhos rápidos que têm o impacto mais real.