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.

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.