A forma correta de fazer isso é tratar WhatsApp como camada de notificação, não como sistema de monitoramento. Você continua monitorando com ferramentas e sinais confiáveis (uptime, métricas, logs, filas, erros), mas centraliza o envio e a governança dos alertas em um lugar só — e aí o Notifish entra bem.

A ideia é simples: qualquer evento relevante → vira um “evento de notificação” → Notifish entrega no WhatsApp.

O que vale a pena mandar para o WhatsApp (e o que não vale)

WhatsApp deve receber só o que exige ação ou atenção rápida. Em produção, eu separo em três níveis:

Crítico (manda sempre):

• aplicação fora do ar / endpoint crítico fora
• erro 5xx em alta (explosão de taxa de erro)
• fila parou de consumir / backlog crescendo rápido
• disco quase cheio / risco de indisponibilidade
• falha em integração crítica (pagamento, mensagens, etc.)

Alerta (manda com filtro):

• latência acima do normal por X minutos
• aumento gradual de erros específicos
• Redis indisponível (com fallback) ou lento
• uso de CPU/memória alto por período sustentado

Informativo (geralmente não manda no WhatsApp):

• deploy realizado
• logs de rotina
• warnings esporádicos

O que destrói o canal é “alerta informativo demais”. WhatsApp é para sinal forte.

Arquitetura recomendada (sem gambiarra)

O melhor padrão é este:

1. Você tem fontes de evento (monitoramento/observabilidade):

• Uptime/health-check (aplicação)
• Métricas do servidor (CPU, RAM, disco)
• Logs (erros específicos, padrões)
• Erros de aplicação (exceptions)
• Filas (backlog, falhas, retries)

2. Um “gerador de eventos” cria um evento padronizado.
3. Você envia esse evento para o Notifish via API.
4. Você define roteamento, deduplicação e templates

• para qual número/grupo enviar
• se deve agrupar, deduplicar, aplicar rate limit
• qual template usar (curto, completo, escalonamento)

Esse desenho escala porque você não espalha envio de WhatsApp por todo sistema. Você centraliza.

Como fica uma mensagem boa no WhatsApp

Uma mensagem útil precisa ter contexto mínimo e ação sugerida:

• Título curto (o que aconteceu)
• Ambiente (prod, staging)
• Serviço (api, worker, site)
• Sintoma (erro, timeout, backlog)
• Impacto (estimado)
• Link (dashboard/logs, se existir)
• Ação recomendada (1 linha)

Exemplo de payload humano:

ALERTA CRÍTICO: API 5xx alto
Ambiente: prod | Serviço: api
Erros 5xx: 18% (últimos 5 min)
Endpoint: /api/orders
Ação: verificar logs + dependência “Payments”

Implementação via API com Notifish (modelo prático)

Você pode integrar de dois jeitos:

1) Seu sistema envia eventos diretamente (Laravel, cron, scripts)

Bom quando você mesmo detecta (fila, logs, métricas internas).

2) Ferramentas externas chamam o Notifish (uptime/monitoramento)

Bom para health-check e métricas do servidor (quando a ferramenta já faz o “detector”).

Como você pediu implementação via API, vou te mostrar um modelo que funciona bem

Payload recomendado (evento)

{
  "message": "Sua mensagem de alerta",
  "identifier": "seu identificador único de disparo",
  "link": true,
  "typing": "composing",
  "delayMessage": 1200
}

Por que esse formato funciona:

• identifier: chave de deduplicação / idempotência do alerta
• message: texto já formatado com contexto (ambiente/serviço/ação)
• delayMessage/typing: ajustes de entrega (opcionais)

Exemplo em Laravel enviando evento ao Notifish

class NotifishClient
{
    public function sendToGroups(string $message, string $identifier, bool $link = true, int $delayMs = 0, string $typing = 'composing'): void
    {
        $url = rtrim(config('services.notifish.base_url'), '/')
            . '/api/v2/' . config('services.notifish.instance')
            . '/whatsapp/message/groups';

        $payload = [
            'message' => $message,
            'identifier' => $identifier,
            'link' => $link,
            'typing' => $typing,
            'delayMessage' => $delayMs,
        ];

        $response = Http::withToken(config('services.notifish.token'))
            ->acceptJson()
            ->contentType('application/json')
            ->timeout(8)
            ->post($url, $payload);

        if (!$response->successful()) {
            logger()->error('Notifish send failed', [
                'status' => $response->status(),
                'body' => $response->body(),
                'identifier' => $identifier,
            ]);
        }
    }
}

Regras importantes para não virar caos

Se você fizer só “manda mensagem”, em 2 semanas o canal morre. Algumas regras que eu considero obrigatórias:

1) Deduplicação

• Todo alerta precisa de dedupe_key.
• Se o mesmo alerta acontecer 100 vezes, você manda 1 e “atualiza”/agrupa.

2) Rate limit por severidade

• Crítico: pode repetir, mas com intervalo mínimo (ex.: 5–10 min).
• Alerta: intervalo maior (ex.: 15–30 min).
• Informativo: geralmente fora do WhatsApp.

3) Idempotência

• Eventos iguais devem produzir o mesmo estado.
• Se a chamada repetir, não deve disparar em duplicidade.

4) Conteúdo curto
WhatsApp é leitura rápida. Se precisar detalhe, coloque em meta e mande link para logs/dashboard quando possível.

5) Escalonamento
Se continuar crítico por X tempo, notifica outro grupo/gestor.

O que monitorar para disparar eventos úteis (fontes típicas)

Você pode começar com estes gatilhos (são os que mais dão retorno):

• Health-check HTTP (200/500, tempo de resposta, quedas)
• Taxa de erro (5xx e exceções por minuto)
• Fila (backlog, jobs failed, tempo médio)
• Banco (conexões, queries lentas, timeouts)
• Redis (latência, indisponibilidade, memória/eviction)
• Servidor (disco, load alto sustentado)
• Integrações externas (timeout e falha por janela)

Monitorar “pelo WhatsApp” não é substituir observabilidade por chat. É transformar sinais importantes em alertas acionáveis, com governança. O Notifish entra como a peça que centraliza o envio e impede que cada sistema invente seu próprio jeito de notificar.

Se você faz dedupe, rate limit, severidade e contexto mínimo, o WhatsApp vira um canal confiável — e não um spam de produção.

The post Como monitorar aplicação e servidor pelo WhatsApp (logs, erros e alertas) appeared first on Leonardo Nascimento | Engenheiro de Software.

Mais do que uma nota colorida, o Lighthouse é uma ferramenta de diagnóstico. Saber usá-lo corretamente evita decisões erradas e otimizações inúteis.

O que é o Lighthouse

O Lighthouse é uma ferramenta automatizada de auditoria de páginas web. Ele analisa uma URL e gera um relatório com métricas e recomendações em cinco áreas principais:

• Performance
• Acessibilidade
• Boas práticas
• SEO
• Progressive Web App (PWA)

O objetivo não é apenas pontuar o site, mas mostrar onde estão os gargalos reais.

Onde o Lighthouse está disponível

Você pode usar o Lighthouse de várias formas:

• Chrome DevTools (nativo do navegador)
• Linha de comando (CLI)
• CI/CD (auditorias automatizadas)
• Ferramentas online baseadas no Lighthouse

Para a maioria dos casos, o DevTools já resolve bem.

Como rodar o Lighthouse pelo Chrome

1. Abra o site no Chrome
2. Pressione F12 ou Ctrl + Shift + I
3. Vá até a aba Lighthouse
4. Escolha o tipo de dispositivo (Mobile ou Desktop)
5. Clique em Generate report

Em poucos segundos, o relatório é gerado.

As métricas mais importantes (e o que elas significam)

Performance

Avalia tempo de carregamento e resposta da página. Algumas métricas-chave:

• LCP (Largest Contentful Paint)
  Mede quando o maior elemento visível aparece. Impacta diretamente a percepção de velocidade.
• INP (Interaction to Next Paint)
  Avalia a resposta do site às interações do usuário.
• CLS (Cumulative Layout Shift)
  Mede instabilidade visual (elementos “pulando” na tela).

Essas métricas fazem parte do Core Web Vitals, usados pelo Google como sinal de experiência.

Acessibilidade

Verifica se o site pode ser usado por pessoas com limitações visuais, motoras ou cognitivas. Exemplos de checagem:

• contraste de cores
• textos alternativos em imagens
• labels em formulários
• estrutura semântica do HTML

Mesmo que não seja um requisito legal em todos os casos, acessibilidade melhora usabilidade para todos.

Boas práticas

Aqui entram problemas mais técnicos, como:

• uso de APIs inseguras
• imagens com proporções erradas
• erros de console
• bibliotecas desatualizadas

É uma área que ajuda a manter o site saudável ao longo do tempo.

SEO

O Lighthouse não substitui ferramentas avançadas de SEO, mas valida o básico:

• meta tags essenciais
• indexabilidade
• uso correto de links
• estrutura mínima de conteúdo

Se o site falha aqui, dificilmente terá bom desempenho orgânico.

O erro mais comum: otimizar só para a nota

Muita gente usa o Lighthouse como competição de pontuação. Isso é um erro.

Um site pode ter nota 100 e ainda assim:

• carregar dados desnecessários
• ter arquitetura ruim
• sofrer em cenários reais de tráfego

O relatório deve ser lido como ferramenta de diagnóstico, não como objetivo final.

Mobile vs Desktop: sempre priorize mobile

O Google avalia sites com mobile-first indexing. Isso significa que:

• o relatório mobile é mais relevante
• problemas no mobile impactam mais SEO
• otimizações devem começar pelo mobile

Um site rápido no desktop e lento no celular está em desvantagem.

Lighthouse em produção e CI/CD

Em projetos mais maduros, o Lighthouse pode rodar automaticamente:

• antes de deploy
• após mudanças críticas
• em pipelines de CI/CD

Isso ajuda a evitar regressões de performance e garante que melhorias não sejam perdidas com o tempo.

Limitações do Lighthouse

Apesar de poderoso, o Lighthouse tem limites:

• roda em ambiente controlado
• não reflete todos os cenários reais
• não substitui métricas de usuários reais (RUM)

O ideal é combiná-lo com dados reais de uso, como relatórios de experiência de campo.

Quando o Lighthouse faz mais diferença

Ele é especialmente útil para:

• identificar gargalos iniciais de performance
• validar mudanças estruturais
• educar times sobre impacto técnico
• criar baseline de qualidade

Não é uma bala de prata, mas é um excelente ponto de partida.

O Lighthouse não serve para “tirar nota alta”, mas para entender como o site se comporta do ponto de vista do usuário. Quando usado com critério, ele direciona otimizações que realmente fazem diferença.

Ignorá-lo pode custar performance, experiência e visibilidade. Usá-lo mal pode custar tempo. O valor está em interpretar os dados, não apenas executá-los.

The post O que é Lighthouse e como usar para melhorar seu site appeared first on Leonardo Nascimento | Engenheiro de Software.

CI/CD não é sobre velocidade. É sobre previsibilidade, repetibilidade e segurança no processo de entrega.

O que CI/CD realmente resolve em projetos Laravel

Em aplicações Laravel, o pipeline de deploy resolve três problemas clássicos:

1. Ambiente inconsistente
   O código roda local, mas quebra em produção porque algo foi esquecido ou executado fora de ordem.
2. Deploys inseguros
   Código sobe sem testes, sem validação, sem rollback fácil.
3. Processo dependente de pessoas
   “Só fulano sabe fazer deploy”. Quando ele não está, ninguém sobe nada.

CI/CD elimina esses pontos ao transformar deploy em processo automatizado, não em ritual manual.

Conceito básico do pipeline (independente da ferramenta)

Antes de falar de GitHub Actions ou GitLab CI, é importante entender o fluxo lógico. Um pipeline de Laravel bem definido costuma ter estas etapas:

1. Checkout do código
2. Instalação de dependências
3. Execução de testes
4. Build (quando aplicável)
5. Deploy
6. Pós-deploy (migrations, cache, filas)

Se qualquer etapa falhar, o deploy não acontece. Isso é uma proteção, não um obstáculo.

Estrutura mínima de um deploy Laravel saudável

Independente de cloud ou CI, alguns princípios não mudam:

• composer install sempre em modo produção
• .env nunca versionado
• APP_ENV e APP_DEBUG corretos
• migrations rodando de forma controlada
• cache/config/views limpos e recompilados
• workers reiniciados corretamente

Se isso não estiver automatizado, o risco é constante.

Exemplo de pipeline com GitHub Actions

Um pipeline simples, mas funcional, usando GitHub Actions:

name: Deploy Laravel

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.2'
          extensions: mbstring, pdo, pdo_mysql

      - name: Install dependencies
        run: composer install --no-dev --optimize-autoloader

      - name: Run tests
        run: php artisan test

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SERVER_SSH_KEY }}
          script: |
            cd /var/www/app
            git pull origin main
            composer install --no-dev --optimize-autoloader
            php artisan migrate --force
            php artisan optimize
            php artisan queue:restart

Onde muita gente erra no deploy de Laravel

Rodar migration sem pensar em impacto

Migration em produção pode travar tabela, gerar lentidão ou indisponibilidade. CI/CD não elimina isso. Ele apenas automatiza. Migration precisa ser escrita com consciência de produção.

Cache mal tratado

Não limpar/recriar cache de config e routes gera bugs difíceis de explicar. Cache antigo em produção é clássico.

Workers esquecidos

Deploy sobe código novo, mas workers continuam rodando código antigo. Resultado: comportamento inconsistente.

Falta de rollback

CI/CD sem rollback é metade da solução. Mesmo que seja manual, precisa existir um caminho claro para voltar.

Estratégia simples de rollback

Mesmo sem blue/green ou canary, dá para ter rollback básico:

• manter tags ou releases
• usar git checkout para versão anterior
• rodar php artisan migrate:rollback quando aplicável
• reiniciar workers

O importante é ter plano. Não improvisar sob pressão.

CI/CD não substitui observabilidade

Deploy automatizado reduz erro humano, mas não impede bugs. Por isso, CI/CD precisa andar junto com:

• monitoramento de erros
• alertas pós-deploy
• logs estruturados
• métricas de saúde

Deploy sem visibilidade é só um erro mais rápido.

CI/CD em projetos Laravel não é luxo nem modinha. É uma camada básica de segurança operacional. Ele garante que o código passe sempre pelo mesmo caminho, reduz risco humano e cria previsibilidade no processo de entrega.

Quando o deploy deixa de ser um evento tenso e vira algo rotineiro, o time ganha confiança para evoluir o sistema. E isso, no fim, é o que permite crescer sem quebrar tudo a cada release.

The post Deployment de Laravel no Cloud com CI/CD (GitHub Actions e GitLab CI) appeared first on Leonardo Nascimento | Engenheiro de Software.

Quando alguém usa “funciona local” como argumento técnico, geralmente está ignorando o contexto em que o sistema realmente vai operar. E é exatamente aí que os problemas começam.

Em local, você tem controle total. O banco está limpo, a latência é praticamente zero, não existem requisições concorrentes, não há retries, não há jobs acumulados, não há serviços externos oscilando. Você executa uma ação, olha o resultado e segue em frente. É um ambiente artificialmente perfeito.

Produção é o oposto disso.

A primeira diferença aparece com concorrência. Localmente, você clica uma vez. Em produção, dezenas ou centenas de usuários fazem a mesma ação ao mesmo tempo. Jobs rodam em paralelo. Requests competem por recursos. Código que nunca apresentou problema começa a gerar condição de corrida, duplicidade de execução e dados inconsistentes. Nada disso aparece no teste local simples.

Outra diferença crítica é latência. Em local, chamadas HTTP e queries são praticamente instantâneas. Em produção, uma API externa pode demorar segundos para responder, ou responder de forma intermitente. Um banco pode ficar lento sob carga. Um cache pode expirar no pior momento. Código que assume resposta imediata funciona local, mas degrada ou trava em produção.

Existe também a questão do volume de dados. Local costuma ter poucos registros. Produção tem milhares ou milhões. Queries que pareciam inofensivas passam a consumir tempo e recursos. Loops simples viram gargalo. Processamentos que eram aceitáveis começam a estourar timeout. O problema não é o código “errado”, é o código não preparado para escala.

Dependências externas são outro ponto ignorado em ambiente local. Muitas vezes você testa com mock, sandbox ou serviço estável. Em produção, serviços externos falham, ficam lentos ou retornam dados inesperados. Se o sistema não foi desenhado para lidar com isso, o erro externo vira indisponibilidade interna.

Local também não expõe problemas de observabilidade. Em produção, quando algo dá errado, você precisa responder rápido: o que aconteceu, quando, com qual dado, em qual fluxo. Código que “funciona local” mas não gera logs úteis transforma qualquer incidente em uma investigação longa e cara.

Outro ponto comum é configuração e ambiente. Local costuma ter permissões amplas, cache limpo, variáveis simples. Produção tem múltiplos ambientes, secrets, variáveis diferentes, limites de recurso e regras de segurança. Código que assume configuração fixa funciona local e quebra fora dele.

Existe ainda o fator tempo. Local você testa agora. Produção roda por semanas ou meses. Vazamentos de memória, acúmulo de jobs, crescimento de filas e degradação progressiva só aparecem com o tempo. “Funciona local” raramente considera isso.

Nada disso significa que testar local não importa. Significa que teste local valida comportamento, não valida operação. Ele é necessário, mas está longe de ser suficiente.

Código pronto para produção é aquele que:

• lida bem com concorrência
• assume latência e falha
• escala com dados reais
• é observável
• se comporta de forma previsível sob estresse

Sem isso, o “funciona local” vira apenas uma falsa sensação de segurança.

“Funciona local” não é critério de qualidade. É apenas o primeiro degrau. Produção cobra decisões que local nunca vai cobrar: resiliência, previsibilidade e responsabilidade técnica.

Quando alguém entende isso, muda a forma de escrever código. Quando não entende, continua apagando incêndio e se perguntando por que algo que “funcionava perfeitamente” começou a falhar sem explicação.

The post Na minha máquina funciona. Vamos levar sua máquina para o usuário então appeared first on Leonardo Nascimento | Engenheiro de Software.

O objetivo não é “garantir que nunca execute duas vezes”. O objetivo é garantir que executar duas vezes não cause dano.

Abaixo estão as estratégias que realmente funcionam em projetos Laravel médios e grandes.

1) Torne o job idempotente (regra número 1)

Idempotência significa: rodar uma vez ou dez vezes dá o mesmo resultado final.

Isso é o que separa um job saudável de um job que vai te dar dor de cabeça.

Exemplos práticos:

• “enviar notificação”: marque como enviado e não envie novamente se já estiver enviado.
• “gerar fatura”: use uma chave única e não crie duas faturas para o mesmo evento.
• “sincronizar pedido”: atualize o registro existente em vez de criar um novo.

Em termos práticos, idempotência quase sempre vira: checar estado antes de executar e persistir o estado depois.

2) Use chave idempotente por evento (event_id / request_id)

Toda vez que o seu sistema gera um job, ele deveria ter um identificador estável do evento.

Exemplo:

• event_id do webhook recebido
• message_id da sua tabela
• order_id + status (depende do caso)
• um UUID de “processamento” gerado quando o evento nasceu

Aí você registra algo como:

• “event_id X já foi processado”
• “order_id Y já teve ação Z executada”

O melhor lugar para isso quase sempre é o banco, porque é fonte de verdade.

3) Garanta unicidade no banco (constraints salvam sistemas)

Se duplicidade causa duplicação de registro, não confie só em lógica de aplicação. Use o banco como proteção.

Exemplos:

• índice unique em invoice(event_id)
• unique em notifications(message_id, channel)
• unique em syncs(external_id)

A aplicação tenta criar; se já existe, você trata e segue.

Isso é robusto porque:

• funciona mesmo com múltiplos workers
• não depende de timing perfeito
• reduz risco de corrida

4) Locks distribuídos (Redis) para evitar concorrência

Locks são úteis quando você quer garantir que apenas um worker execute determinada seção crítica ao mesmo tempo.

Exemplo:

• processar um mesmo order_id
• consolidar um relatório
• importar lote único

Em Laravel, dá pra fazer lock via cache (Redis):

• lock por chave: lock:order:123
• se não adquirir, outro worker já está executando

Importante: lock não substitui idempotência. Ele reduz concorrência, mas não garante que um retry nunca vai rodar depois.

5) Use “unique jobs” do Laravel (quando couber)

Laravel tem suporte para jobs únicos (dependendo da versão/config), mas isso é mais útil para evitar enfileirar duplicado, não para evitar execução duplicada em qualquer cenário.

Use se:

• você quer impedir spam de job igual
• o job é claramente único por chave
• você entende as limitações (especialmente com retries e falhas)

Mesmo com unique job, eu continuo recomendando idempotência + banco.

6) Controle retries, timeout e backoff com critério

Muita duplicidade aparece porque:

• job estoura timeout → worker mata → tenta de novo
• job demora demais → você acha que falhou → reprocessa manualmente
• dependência externa oscila → retries “na pancada”

Ajuste bem:

• timeout realista (nem baixo demais, nem infinito)
• tries coerente com o impacto
• backoff crescente para não sobrecarregar dependência externa

O objetivo é evitar “tempestade de retries”.

7) Separe “efeito colateral” do “estado principal”

Quando duplicidade é perigosa, normalmente é porque o job faz um efeito colateral irreversível (ex: cobrar cartão, enviar WhatsApp, emitir nota). A abordagem mais segura é:

1. persistir um estado interno (“pendente”, “processando”, “concluído”)
2. só então executar o efeito colateral
3. registrar resultado e contexto

Isso cria trilha de auditoria e evita “executar no escuro”.

8) Instrumente: trace por job e correlação

Você só descobre duplicidade tarde se não tiver rastreabilidade.

Boas práticas:

• job_id/correlation_id em logs
• logar início/fim do job com chave do evento
• métrica de “job duplicado evitado” (sim, isso ajuda muito)

Quando dá problema, você quer saber: “por que rodou duas vezes?” em 2 minutos, não em 2 horas.

Um padrão simples que funciona muito bem

Se eu tivesse que resumir num padrão prático:

• chave idempotente (event_id)
• tabela de processamento (processed_events) com unique
• lock Redis opcional em trechos críticos
• constraints no banco para proteger criação duplicada
• logs com correlação

Isso cobre 95% dos casos reais.

Em produção, duplicidade em job não é exceção. É comportamento esperado do mundo real (retries, falhas, concorrência). O caminho profissional é aceitar isso e desenhar o job para ser seguro.

Job bom é o que pode rodar duas vezes sem te acordar de madrugada.

The post Como evitar duplicidade de processamento em jobs appeared first on Leonardo Nascimento | Engenheiro de Software.

Estruturar um projeto Laravel bem não é sobre “inventar arquitetura”. É sobre reduzir atrito: facilitar manutenção, evitar acoplamento desnecessário e deixar o código previsível para quem chega depois.

A seguir estão práticas que funcionam bem em projetos médios e grandes, especialmente quando já existe operação de produção, roadmap e mudanças frequentes.

Comece pela regra: controller não é lugar de lógica

Controller deveria orquestrar: receber request, validar, chamar a camada certa e responder. Quando regra de negócio fica no controller, você cria um ponto de acoplamento difícil de testar e difícil de reutilizar. Em projeto grande isso vira padrão ruim rapidamente, porque todo mundo copia o que já existe.

O que funciona melhor é mover lógica para classes dedicadas (services/use cases/actions), e deixar o controller como uma “casca” fina. Você ganha clareza, reaproveitamento e testes mais simples.

Estruture por domínio (feature) quando o sistema crescer

A estrutura padrão do Laravel (Controllers, Models, Jobs, etc.) é ótima até um certo ponto. Em sistemas grandes, ela tende a espalhar a mesma funcionalidade por várias pastas e o dev precisa “caçar” arquivos para entender um fluxo.

Uma abordagem que escala melhor é organizar por domínio/feature. Exemplo: tudo relacionado a “Billing” fica próximo (requests, actions, policies, resources, etc.). Isso reduz a fricção para manter e evoluir partes específicas do sistema.

Você não precisa mudar tudo de uma vez. Dá para começar com um ou dois domínios e ir migrando aos poucos, sem reescrever o projeto inteiro.

Estrutura tradicional do Laravel (por tipo)

app/
├── Http/
│   ├── Controllers/
│   ├── Requests/
│   └── Resources/
├── Models/
├── Jobs/
├── Policies/
├── Services/

Problema em projeto grande:
para entender Billing, você precisa abrir 6 pastas diferentes.

Estrutura por domínio / feature

app/
└── Domains/
└── Billing/
├── Http/
│ ├── Controllers/
│ ├── Requests/
│ └── Resources/
├── Actions/
├── Jobs/
├── Policies/
├── Models/
└── Services/

Ou até mais simples:

app/
└── Billing/
    ├── BillingController.php
    ├── CreateInvoice.php
    ├── Invoice.php
    ├── InvoicePolicy.php
    ├── SendInvoiceJob.php
    └── InvoiceResource.php

O Laravel não se importa com a pasta, desde que o namespace esteja correto.

Por que isso escala melhor?

Porque quando alguém entra no projeto e precisa mexer em Billing:

• não precisa caçar arquivos espalhados
• não quebra coisas de outros domínios
• entende o fluxo mais rápido
• reduz medo de alterar código

Em projeto grande, isso faz muita diferença.

Requests e validações como primeiro filtro

Em projeto grande, dado ruim entrando vira bug caro. Centralizar validação em Form Requests mantém o controller limpo e torna regras de entrada explícitas.

Além disso, vale padronizar:

• mensagens de erro;
• formatos de resposta (principalmente APIs);
• validações compartilhadas (traits, rules customizadas).

Quando a validação é consistente, o sistema vira mais previsível e o time para de reinventar a roda a cada endpoint.

Padronize respostas de API desde cedo

Quando cada endpoint responde de um jeito, cada client precisa de lógica diferente, e isso vira dívida técnica distribuída. Para projetos médios e grandes, uma camada consistente de resposta é obrigatória: Resources, transformers, ou uma padronização interna.

O ponto aqui não é “estética”. É operação. Quando algo quebra, você quer logs previsíveis, payload previsível, erros previsíveis. Isso reduz tempo de diagnóstico.

Regras de negócio: não misture persistência com decisão

Um erro comum em Laravel é “decidir” coisas dentro de models e ao mesmo tempo persistir em todo lugar, sem fronteira clara. Em sistemas maiores, o ideal é separar:

• Decisão / regra (o que pode ou não pode)
• Persistência (salvar, consultar)
• Orquestração (fluxo do caso de uso)

Isso permite evoluir regra sem quebrar camada de persistência, e vice-versa. E facilita testar o que realmente importa: a regra.

Jobs, filas e idempotência não são detalhe

Em projeto grande, você inevitavelmente vai para filas: e-mails, notificações, integrações, processamento pesado. O que quebra sistemas grandes não é “usar fila”. É usar fila sem cuidado com:

• idempotência (job rodar duas vezes sem duplicar efeito);
• retries (quando deve tentar de novo e quando deve falhar);
• timeouts;
• dead letter / estratégia para falhas recorrentes;
• logs por job.

Se o seu projeto depende de integração externa, trate isso como cenário normal: o externo vai falhar. A fila é o lugar certo para absorver isso, desde que bem desenhado.

Serviços externos: isole e trate como dependência instável

Integrações externas deveriam estar em classes próprias (clients/adapters), com:

• timeout explícito;
• tratamento de erro consistente;
• retry controlado quando fizer sentido;
• logs contextualizados.

Evite espalhar Http::post() por todo lugar. Em projeto grande isso vira caos, porque não existe ponto único para ajustar comportamento (ex: mudar header, adicionar auth, alterar timeout).

Migrations, seeds e dados de referência bem cuidados

Projeto grande normalmente tem muita migration. E migration desorganizada vira armadilha: ambientes quebram, dev novo não sobe projeto, staging fica inconsistente.

Boas práticas que ajudam:

• migrations com nomes claros;
• dados de referência (enums/tabelas fixas) com seeders idempotentes;
• evitar “seed que depende de estado manual”;
• sempre testar “do zero” em ambiente limpo.

Isso evita que o setup do projeto vire uma gincana.

Configuração: tudo em config e .env, nada hardcoded

Quando cresce, o sistema precisa rodar em múltiplos ambientes e, muitas vezes, múltiplos clientes. Configuração hardcoded vira problema de deploy e vira risco de segurança.

Padronize:

• config/*.php como fonte de configuração;
• .env apenas para valores variáveis;
• nunca commitar senhas e keys;
• e preferencialmente separar integrações por “config + service container”.

Observabilidade: logs estruturados desde o começo

Em projetos grandes, o custo de “descobrir o que aconteceu” é alto. Sem logs bons você perde tempo, perde confiança e perde previsibilidade operacional.

O que vale padronizar:

• logs com contexto (tenant, user_id, request_id, correlation_id);
• níveis corretos (info, warning, error);
• logs de integrações e jobs;
• e um formato consistente (para facilitar busca).

Isso é o que transforma incidentes em diagnóstico rápido.

Testes: foque no que dá retorno real

Não dá para testar tudo em projeto grande, e tentar fazê-lo costuma falhar. O que dá mais retorno é:

• testes de regras de negócio (unit/integration);
• testes de fluxos críticos;
• testes de contratos de API;
• e testes de integração com serviços externos (com mocks ou ambientes controlados).

Teste não é para “subir porcentagem”. É para reduzir risco onde mais dói.

Conclusão

Projetos Laravel grandes não quebram porque Laravel é limitado. Eles quebram porque a base cresce sem estrutura, sem padrões e sem fronteiras claras entre responsabilidades.

Se você mantiver controllers finos, separar domínio/feature, isolar integrações, tratar filas com seriedade e padronizar validação/retorno/log, o projeto continua evoluindo sem virar um monstro. E o melhor: o time consegue manter velocidade sem sacrificar estabilidade.

The post Boas práticas para estruturar projetos em Laravel de médio e grande porte appeared first on Leonardo Nascimento | Engenheiro de Software.