Este artigo detalha a arquitetura de uma API REST desenvolvida em Laravel para gerenciamento de tarefas, criada como parte de um teste técnico, mas estruturada como um projeto pronto para produção, seguindo boas práticas amplamente utilizadas em ambientes corporativos.

Visão geral da solução

A aplicação consiste em uma API RESTful para gerenciamento de tarefas, com suporte a:

• Autenticação via Bearer Token (Laravel Sanctum)
• CRUD completo de tarefas
• Marcação de tarefas como concluídas
• Cache de consultas com Redis
• Banco de dados PostgreSQL
• Documentação interativa via Swagger
• Ambiente Dockerizado (dev, test e prod)
• Testes automatizados
• Pipeline de CI/CD com GitHub Actions

O foco não foi apenas “fazer funcionar”, mas pensar a aplicação como um produto escalável e previsível.

Decisão arquitetural: API stateless e autenticação

A API foi construída como stateless, utilizando Bearer Token via Laravel Sanctum.

Benefícios dessa abordagem:

• Facilidade de integração com frontends (SPA, mobile, terceiros)
• Independência de sessão
• Escalabilidade horizontal
• Compatibilidade com gateways, load balancers e proxies

A autenticação é desacoplada do fluxo de negócio, o que facilita manutenção e evolução futura.

PostgreSQL como banco principal

A escolha do PostgreSQL não foi aleatória. Ele é amplamente utilizado em ambientes corporativos por oferecer:

• Confiabilidade transacional
• Suporte avançado a índices
• Tipos de dados ricos
• Excelente desempenho em cenários complexos

Isso torna a aplicação preparada para crescer sem precisar trocar a base de dados no curto ou médio prazo.

Redis como camada de cache

Para reduzir carga no banco e melhorar tempo de resposta, foi implementado cache com Redis, com TTL de 120 segundos nas consultas mais comuns.

Benefícios diretos:

• Redução de queries repetitivas
• Menor latência
• Melhor desempenho sob carga
• Escalabilidade em leitura

Essa abordagem demonstra preocupação com performance real, não apenas com lógica funcional.

Arquitetura limpa: Repository Pattern + Service Layer

A aplicação segue princípios de Clean Architecture, separando responsabilidades de forma clara:

• Controllers: recebem requisições e retornam respostas
• Services: concentram regras de negócio
• Repositories: isolam o acesso a dados
• Models: representam as entidades

Vantagens dessa separação:

• Código mais legível
• Facilidade de testes
• Menor acoplamento
• Evolução segura do domínio

Essa estrutura é comum em times maduros e projetos de longo prazo.

Docker como base do ambiente

Toda a aplicação roda em Docker, com ambientes bem definidos:

Desenvolvimento

• Código em volume
• Hot reload
• PostgreSQL + Redis + Nginx
• Testes executados automaticamente

Produção

• Build otimizado
• Código embutido na imagem
• Assets compilados no build
• Sem dependência de volume

Essa separação reduz o clássico problema de “funciona na minha máquina” e aproxima o ambiente local da produção.

Testes automatizados como parte do fluxo

A aplicação conta com testes unitários e de feature, executados de três formas:

• Localmente no ambiente dev
• Isoladamente via Docker
• Automaticamente no CI/CD

Isso garante:

• Segurança para refatorações
• Detecção precoce de bugs
• Confiança na entrega contínua

Testes não são tratados como opcional, mas como parte da arquitetura.

CI/CD com GitHub Actions

Cada push ou pull request dispara um workflow que:

1. Sobe toda a stack Docker (app, banco, cache)
2. Executa migrations
3. Roda a suíte completa de testes
4. Bloqueia o merge em caso de falha

Esse processo simula um pipeline real de empresas que operam com entrega contínua e qualidade de código como requisito.

Documentação com Swagger

A API possui documentação interativa via Swagger, acessível após subir a aplicação.

Isso permite:

• Testes manuais rápidos
• Onboarding mais fácil
• Comunicação clara entre backend e frontend
• Uso por terceiros sem dependência de documentação externa

Documentação é tratada como parte do produto, não como etapa posterior.

Benefícios dessa arquitetura em um contexto profissional

Essa abordagem entrega vantagens claras em ambientes reais:

• Código organizado e previsível
• Facilidade de manutenção
• Escalabilidade técnica
• Padronização de ambientes
• Menor risco em deploys
• Base sólida para crescimento

Não se trata apenas de uma API de tarefas, mas de um modelo replicável para aplicações reais.

O que esse projeto demonstra tecnicamente

Esse projeto evidencia competências como:

• Domínio de Laravel além do básico
• Conhecimento de arquitetura backend
• Uso consciente de cache e banco
• Experiência com Docker e ambientes reais
• Cultura de testes
• Automação de CI/CD
• Pensamento orientado a produto e escala

São exatamente esses pontos que diferenciam um desenvolvedor pleno/sênior em processos seletivos.

Conclusão

Mais do que cumprir um teste técnico, o objetivo deste projeto foi demonstrar capacidade de pensar sistemas como um todo, indo além do CRUD simples.

Arquitetura, automação, testes e previsibilidade são o que tornam uma aplicação sustentável — e é isso que empresas buscam quando contratam profissionais para projetos de longo prazo.

Link do teste prático

The post Arquitetura de uma API REST em Laravel preparada para produção appeared first on Leonardo Nascimento | Engenheiro de Software.

O que diferencia um dev mais experiente não é o que ele sabe fazer, mas o que ele evita fazer.

Vou te ensinar aqui um padrão prático, usado em projetos reais, que resolve três problemas clássicos:

• Controllers inchados
• Regras de negócio espalhadas
• Código impossível de testar ou evoluir

public function store(Request $request)
{
if (!$request->email) {
return response()->json([‘error’ => ‘Email obrigatório’], 422);
}

$user = User::create([
    'name' => $request->name,
    'email' => $request->email,
]);

Mail::to($user->email)->send(new WelcomeMail($user));

Log::info('Usuário criado', ['id' => $user->id]);

return response()->json($user);

}

Funciona? Funciona.

É bom? Não.

Por quê?

• Controller decide regra de negócio
• Controller cria usuário
• Controller dispara e-mail
• Controller registra log

Isso acopla tudo.

Pensamento pleno/sênior: separar responsabilidade

Controller não decide regra.
Controller orquestra.

Vamos refatorar com um Service + DTO, padrão simples e poderoso.

Criando um DTO (Data Transfer Object)

Isso evita Request sendo usado como regra de negócio.

final class CreateUserDTO
{
    public function __construct(
        public readonly string $name,
        public readonly string $email,
    ) {}
}

Simples, explícito e tipado.

Criando o Service (onde a regra mora)

final class CreateUserService
{
    public function execute(CreateUserDTO $dto): User
    {
        if (!filter_var($dto->email, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidArgumentException('Email inválido');
        }

        $user = User::create([
            'name' => $dto->name,
            'email' => $dto->email,
        ]);

        Mail::to($user->email)->send(new WelcomeMail($user));

        Log::info('Usuário criado', ['id' => $user->id]);

        return $user;
    }
}

Agora sim:

• Regra centralizada
• Código reutilizável
• Fácil de testar
• Fácil de evoluir

Controller limpo (como deveria ser)

public function store(Request $request, CreateUserService $service)
{
    $dto = new CreateUserDTO(
        name: $request->name,
        email: $request->email
    );

    $user = $service->execute($dto);

    return response()->json($user);
}

O controller:

• Recebe request
• Constrói DTO
• Chama serviço
• Retorna resposta

Nada além disso.

O ganho real (que júnior não enxerga)

Testabilidade

Agora você testa a regra sem framework:

public function test_user_creation()
{
    $service = new CreateUserService();

    $dto = new CreateUserDTO(
        name: 'Leo',
        email: 'leo@email.com'
    );

    $user = $service->execute($dto);

    $this->assertEquals('Leo', $user->name);
}

Sem Request.
Sem Controller.
Sem gambiarra.

Evolução sem dor

Amanhã você precisa:

• Enviar evento para fila
• Criar usuário em sistema externo
• Validar regra nova

Você altera um lugar só.

Mentalidade sênior (isso vale ouro)

” Código que funciona não é código bom.mCódigo bom é o que aguenta mudança.”

Pleno/sênior pensa assim:

• Onde essa regra deve morar?
• O que vai mudar daqui 6 meses?
• Quem vai dar manutenção nisso?

Erros clássicos que isso evita

• Fat models
• Controllers gigantes
• Services que viram controllers
• Regra duplicada
• Código impossível de refatorar

Esse tipo de abordagem não aparece em tutorial de YouTube, mas é exatamente o que mantém sistemas vivos em produção.

The post PHP além do CRUD: como escrever código que não vira problema em produção 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.

A maioria desses problemas não vem do Redis em si, mas da forma como ele é integrado à aplicação. A seguir estão erros que aparecem com frequência em produção e o que aprender com eles.

Um dos erros mais comuns é tratar Redis como banco de dados principal. Redis é rápido, mas não é fonte de verdade. Dados em memória podem ser perdidos por restart, eviction ou falha de infraestrutura. Quando o sistema depende do Redis para manter estado crítico, qualquer limpeza vira incidente. Em aplicações maduras, Redis é sempre camada auxiliar; o banco relacional continua sendo a referência.

Outro problema recorrente é cachear dados sem estratégia clara de invalidação. No começo, tudo parece funcionar: menos queries, respostas mais rápidas. Com o tempo, começam a aparecer dados desatualizados, comportamentos inconsistentes e bugs que “somem sozinhos”. Cache sem invalidação bem definida vira dívida técnica. Toda entrada em cache precisa ter resposta clara para três perguntas: quando expira, quem invalida e o que acontece se falhar.

Também é comum usar TTL genérico para tudo. Definir o mesmo tempo de expiração para dados completamente diferentes ignora o contexto. Dados quase estáticos podem ficar horas em cache; dados sensíveis a mudanças podem precisar de expiração curta ou invalidação ativa. TTL não é detalhe de configuração, é parte da regra de negócio.

Em projetos com filas e jobs, aparece bastante o erro de usar Redis sem pensar em concorrência. Dois workers acessando e alterando a mesma chave ao mesmo tempo geram condição de corrida. Incrementos, flags e estados intermediários precisam ser atômicos ou protegidos por lock. Ignorar isso funciona em teste, mas quebra sob carga.

Outro ponto crítico é usar Redis como solução para idempotência sem persistência complementar. Locks e flags em Redis ajudam, mas não garantem segurança total. Se o Redis reiniciar, o controle some. Para efeitos colaterais críticos (pagamento, notificação, integração externa), o controle final precisa estar no banco, com constraint ou registro explícito de processamento.

Muitos projetos também caem no erro de não separar namespaces ou prefixos de chave. Em aplicações maiores, isso gera colisão, dificuldade de debug e limpeza perigosa. Padronizar prefixos por domínio ou tipo de dado facilita manutenção e evita apagar cache errado.

Há ainda o uso excessivo de Redis para resolver problemas que não são de cache. Guardar lógica de negócio, estados complexos ou fluxos longos em memória costuma deixar o sistema frágil. Redis é ótimo para acelerar acesso, coordenar concorrência e compartilhar estado temporário, mas não substitui modelagem correta.

Outro erro que só aparece em produção é ignorar política de eviction e limites de memória. Quando a memória acaba, o Redis começa a remover chaves de acordo com a política configurada. Se isso não foi considerado no design, o sistema passa a perder cache crítico aleatoriamente, causando degradação inesperada. Monitorar uso de memória e entender eviction é obrigatório.

Também é comum não monitorar Redis como dependência crítica. Quando ele fica lento ou indisponível, a aplicação sofre. Sem métricas, alertas e logs específicos, o diagnóstico demora. Redis precisa estar no radar de observabilidade tanto quanto banco e API externa.

Por fim, um erro sutil: acoplar demais o código ao Redis. Quando a aplicação assume que Redis sempre está disponível, qualquer fallback vira difícil. Código mais saudável trata Redis como otimização opcional: se falhar, o sistema continua funcionando, mesmo que mais lento.

Redis é uma ferramenta poderosa, mas exige disciplina. Em aplicações Laravel, ele deve acelerar, proteger e coordenar — nunca sustentar a lógica principal do sistema. Quando tratado como camada auxiliar, com invalidação clara, controle de concorrência e observabilidade, ele entrega o que promete. Quando usado como atalho, cobra o preço em produção.

The post Erros comuns ao usar Redis em aplicações Laravel 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.

Jobs e processamento assíncrono são excelentes quando usados com critério. Quando usados por impulso, viram fonte de incidentes.

O que fila realmente te dá (e o que ela não dá)

Fila te dá principalmente três coisas: desacoplamento do tempo de resposta, capacidade de absorver picos e reprocessamento controlado. Ela não te dá garantia de que algo vai rodar uma vez só, nem te livra de tratar falhas externas. Na verdade, ela te obriga a tratar isso.

Se você joga um processo para a fila sem pensar em idempotência, retries e observabilidade, você só mudou o problema de lugar.

Quando usar jobs e filas

1) Tudo que não precisa bloquear o usuário

Se o usuário não precisa do resultado imediato, isso já é um sinal forte de fila.

Exemplos comuns:

• envio de e-mail e notificações
• geração de relatórios
• criação de thumbnails / processamento de mídia
• sincronização com sistemas externos
• webhooks de saída (enviar eventos para terceiros)

A regra prática: se o usuário já pode seguir o fluxo sem esperar, tire do request.

2) Integrações externas e chamadas instáveis

API de terceiros falha, oscila, responde lento. Fila é ótima para isso porque permite retries e isolamento.

Exemplos:

• gateway de pagamento
• WhatsApp / SMS
• ERP e sistemas legados
• qualquer HTTP externo

Mas aqui entra o ponto crítico: fila não é desculpa para “tentar infinitamente”. Você precisa controlar tentativas e saber quando desistir.

3) Processamentos pesados e previsíveis

Tudo que consome CPU, memória ou I/O e pode gerar timeout em request tende a ser melhor em job.

Exemplos:

• exportar CSV grande
• processar lote de dados
• recalcular agregações
• rodar rotinas de normalização/validação em massa

4) Fan-out (um evento dispara várias ações)

Quando algo acontece e você precisa executar várias tarefas em sequência ou em paralelo, jobs ajudam a manter o sistema organizado.

Exemplo: “pedido pago” dispara:

• enviar confirmação
• baixar estoque
• emitir nota
• notificar financeiro
• gerar registro no CRM

Se você faz tudo no request, vira um fluxo pesado e frágil. Com jobs, você separa responsabilidades.

5) Absorver picos sem derrubar o sistema

Fila é uma forma de “buffer”. Em vez de o sistema tentar processar tudo na hora e morrer, você coloca em fila e processa no ritmo que aguenta.

Isso é útil quando:

• picos são comuns
• demanda varia muito
• você precisa garantir estabilidade

Quando evitar jobs e filas

1) Quando você precisa de resposta imediata e consistente

Se o usuário precisa saber na hora se deu certo, jogar em fila pode piorar a experiência.

Exemplos:

• login
• criar pagamento e retornar confirmação
• reservar algo que não pode duplicar
• operações transacionais críticas

Você até pode usar job para efeitos colaterais, mas a decisão central precisa ser síncrona.

2) Quando a operação é simples e rápida

Às vezes a operação leva 20ms e você coloca na fila “por padrão”. Isso adiciona:

• complexidade
• delay
• necessidade de monitoramento
• risco de falha assíncrona

Fila não pode ser usada como padrão para tudo. Senão você cria um sistema cheio de jobs pequenos e difíceis de rastrear.

3) Quando você não tem observabilidade

Fila sem visibilidade vira caixa-preta.

Se você não tem:

• logs por job
• métricas de falha
• alertas de backlog
• dead-letter ou estratégia de falha

você vai descobrir problemas tarde demais. Nesse cenário, manter síncrono pode ser mais seguro até organizar a casa.

4) Quando você não consegue garantir idempotência

Jobs podem rodar duas vezes. Isso é normal: retry, timeouts, quedas de worker, reentregas. Se o job não é idempotente, você corre risco de:

• cobrança duplicada
• disparo duplicado
• registro duplicado
• integração duplicada

Se não dá para tornar idempotente, trate o caso com mais cuidado. Às vezes o certo é manter a operação central síncrona e colocar apenas efeitos colaterais na fila.

O ponto que derruba sistemas: duplicidade

Em produção, o seu job vai rodar duas vezes em algum momento. Não é “se”, é “quando”. Por isso, projetos maduros tratam idempotência como requisito.

Algumas abordagens comuns:

• chave idempotente por evento (event_id / request_id)
• lock distribuído (Redis)
• uniqueness controlada (Laravel unique jobs quando aplicável)
• constraints no banco (único onde fizer sentido)

Não é uma bala de prata, mas é obrigatório ter uma estratégia.

Filas também precisam de limites

Jobs não podem tentar para sempre. Você precisa definir:

• número de tentativas
• backoff entre tentativas
• timeout
• comportamento ao falhar (alerta, dead letter, reprocessamento manual)

E precisa aceitar que algumas coisas falham. O sistema não pode entrar em loop eterno tentando recuperar erro externo.

Sinais de que você deve ir para fila

Se você está em dúvida, aqui vão sinais bem práticos:

• requests começando a estourar timeout
• picos derrubando a API
• integrações externas travando fluxos principais
• usuários esperando por coisas que não precisam esperar
• o mesmo fluxo acumulando responsabilidades demais

Jobs e filas são uma das melhores ferramentas para dar escala e estabilidade em sistemas Laravel, mas elas exigem maturidade. Quando bem usadas, melhoram performance, isolam falhas e deixam o sistema mais previsível. Quando usadas sem critério, viram um sistema difícil de operar, cheio de jobs duplicados e incidentes intermitentes.

Fila não é atalho. É arquitetura.

The post Laravel: Jobs, filas e processamento assíncrono: quando usar e quando evitar 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.

Porém, todavia, entretanto, contudo, se você não tem um grande conhecimento em gerenciamento de hospedagens, ou simplesmente não quer se incomodar em prestar suporte para o seu cliente, poderá muito bem optar por um Cloud 100% configurado com:

• Servidor Cloud individual (Apenas o seu site hospedado no Cloud)
• E-mails ilimitados
• SSL grátis
• Firewall
• Tráfego ilimitado
• Banco de dados ilimitados
• Backup grátis
• Acesso SSH
• Software anti-spam para e-mails
• Upgrade/Downgrade de plano direto pelo painel, sem precisar abrir ticket e sem downtime
• Suporte grátis
• Instalações de aplicações com poucos cliques
• Revenda de hospedagem
• Plugin de cache (WordPress)
• Editor de arquivos
• FTP
• Deploy pelo GitLab em breve Github e Bitbucket
• Restauração de backup em poucos cliques
• Gerenciador de banco de dados (PHPMYADMIN)
• Acesso remoto ao banco de dados
• Escolher entre Mysql e PostgreSQL
• Balanceador de carga
• Escolher versões do PHP (5.4 até >= 8.0)
• CronJob direto pelo painel
• Logs de erro do PHP e do servidor
• Migração dos seus dados gratuitamente (Consulte)
• Hospedagem individualizada, sem compartilhamento de CPU e memória com outros sites
• Sem fidelidade (cancele quando quiser)
• A partir de R$ 10,90

Lembrando que o valor de R$ 10,90 é a configuração inicial, se você precisar de mais poder de processamento, poderá efetuar upgrade da sua instância, com valores adicionais.

Sem surpresas na conta

Você está no controle da sua hospedagem, no painel de controle, é possível verificar uma estimativa de quantos créditos você ainda possuí e quanto tempo ele irá durar.

Você pode optar por deixar a recarga automática através de cartão de crédito, também é possível inserir créditos através de boleto bancário, Pix ou mercado pago.

Você no controle

Com a hostoo você está no controle e não precisa ser expert em servidores, é possível efetuar upgrade e downgrade de servidor com poucos cliques e sem deixar o seu site offline. Instale e configure aplicações em poucos cliques. Gosta do WordPress? Plugin de cache gratuito para acelerar ainda mais o carregamento do seu site.

No print abaixo, podemos notar o domínio do site, versão do PHP, SSL ativo, detalhes do plano, detalhes de consumo de CPU, RAM, disco e outras configurações da hospedagem.

Precisa de mais?

Além de ter servidores nos Estados Unidos, também é possível hospedar seus sites em clouds aqui no Brasil, claro, por um valor adicional. Com a Hostoo você pode fazer upgrade de plano facilmente. Suponhamos que durante o dia, você teve visitas atípicas em seu website, resultando em um consumo máximo de CPU e RAM, e agora o que fazer? Em poucos cliques, você pode efetuar upgrade do seu plano, contratando um cloud melhor, pagando por hora utilizada, e posteriormente, retornar ao plano original, você está 100% no controle.

Suporte que não te deixa 48h esperando

Estou com a Hostoo há mais de 1 ano e diferente de outros serviços de hospedagem, o suporte é muito rápido e definitivamente resolve seus problemas. Até o momento, precisei abrir apenas 1 ticket de site fora do ar, onde ficou constatado que o problema não era na hospedagem e sim no servidor dns que eu estava utilizando como proxy, o outro ticket? Foi aberto pela própria empresa, quando me deparei com um erro 500 no painel de hospedagem. Tempo da primeira resposta < 22 minutos.

Sem dúvidas, foi um grande achado que estou compartilhando com você! https://hostoo.io

The post Hospede seu site em um servidor Cloud por menos de R$ 11 Mês appeared first on Leonardo Nascimento | Engenheiro de Software.

Um repositório é uma camada de abstração que separa o acesso a dados de sua lógica de negócios. Isso significa que, em vez de escrever código para acessar diretamente o banco de dados em suas classes de modelo, você pode usar métodos do repositório para realizar operações de banco de dados. Isso pode tornar o seu código mais legível e facilita a manutenção.

Para criar um repositório no Laravel, siga estes passos:

1. Crie uma nova interface de repositório em app/Repositories. Esta interface deve conter métodos para as operações de banco de dados que você deseja realizar (por exemplo, obter todos os registros, obter um registro pelo ID, salvar um novo registro, etc.).
2. Crie uma nova classe de repositório que implemente a interface de repositório criada no passo 1. Esta classe deve conter a lógica para realizar as operações de banco de dados usando a classe de modelo correspondente do Laravel.
3. Adicione o repositório criado ao container de injeção de dependência do Laravel em app/Providers/AppServiceProvider.php. Isso permitirá que o Laravel crie uma instância do repositório quando for necessário.
4. Em sua classe de modelo, adicione uma propriedade privada para a instância do repositório e um construtor que aceite uma instância do repositório como argumento. Isso permitirá que você use o repositório em sua classe de modelo para realizar operações de banco de dados.

<?php

namespace App\Repositories;

interface PostRepositoryInterface
{
  public function getAll();
  public function findById($id);
  public function save($data);
  public function update($id, $data);
  public function delete($id);
}

<?php

namespace App\Repositories;

use App\Models\Post;

class PostRepository implements PostRepositoryInterface
{
  protected $model;

  public function __construct(Post $model)
  {
    $this->model = $model;

The post Como criar um repositório no Laravel appeared first on Leonardo Nascimento | Engenheiro de Software.