RiffHouse API é um backend REST robusto desenvolvido para a plataforma de e-commerce RiffHouse, especializada em instrumentos musicais. O projeto foi construído com Java 21 e Spring Boot 3, adotando padrões arquiteturais modernos para garantir escalabilidade, manutenibilidade e alta performance.
O objetivo principal é demonstrar a aplicação de conceitos avançados de engenharia de software, incluindo Arquitetura Orientada a Eventos, CQRS (Command Query Responsibility Segregation) e estratégias de Concorrência Otimista.
🌐 Live Demo: Acesse a API aqui
⚠️ Nota: O servidor está hospedado no plano gratuito do Render. A primeira requisição pode levar de 1 a 2 minutos para "acordar" a API.
👉 Documentação Interativa (Swagger): Acesse o Swagger UI
A aplicação segue uma Arquitetura em Camadas com estrita separação de responsabilidades. O design foi pensado para resolver problemas reais de concorrência e escalabilidade.
- Abstração Genérica (CRUD Base): Implementação de controladores base (
BaseReadControllereBaseWriteController) e serviços genéricos. Isso garante padronização, reduz código duplicado (DRY) e acelera o desenvolvimento de novas entidades. - CQRS-Lite: Separação física e lógica das operações de Leitura e Escrita. Isso permite otimizar consultas e comandos de forma independente, melhorando a clareza do código.
- Concorrência Otimista (
@Version): Solução para evitar conflitos de estoque (Lost Update Problem). Garante que dois usuários não consigam comprar o último item do estoque simultaneamente, utilizando versionamento de registro no banco de dados. - Arquitetura Orientada a Eventos (RabbitMQ): Processamento assíncrono para tarefas pesadas e lentas (envio de e-mails, processamento de pedidos), desacoplando o fluxo principal e melhorando o tempo de resposta para o usuário.
- Soft Delete: Implementação de exclusão lógica em nível de entidade base, permitindo desativar registros sem perda de histórico de dados.
- Strategy Pattern: Uso de interfaces genéricas
Validator<T>para encapsular regras de negócio complexas, facilitando testes e extensão. - Tratamento Global de Erros:
ApiErrorDTOpara padronização de respostas JSON (RFC 7807 inspired).- Supressão de stacktrace em produção para segurança.
- Exceções personalizadas de negócio.
- Internacionalização (i18n): A API responde mensagens de erro e validação em Inglês ou Português, baseando-se automaticamente no header
Accept-Language.
- Linguagem: Java 21
- Framework: Spring Boot 3.5.5 (Web, Data JPA, Security, Validation, ModelMapper, OpenFeign, AMQP, Mail)
- Banco de Dados: PostgreSQL (Produção/Dev), H2 (Teste)
- Migração: Flyway
- Mensageria: RabbitMQ
- Documentação: SpringDoc OpenAPI (Swagger UI)
- Containerização: Docker e Docker Compose
- Autenticação JWT: Login seguro, validação de token stateless e recuperação de senha via e-mail.
- RBAC (Role-Based Access Control): Sistema de permissões hierárquico. Usuários nascem como
USER; apenasADMINpode elevar privilégios. - Proteção de Dados: Usuários gerenciam apenas seus próprios dados sensíveis, independente do nível de acesso.
- Checkout Assíncrono: O pedido é recebido e processado em background via fila, garantindo alta disponibilidade mesmo em picos de acesso.
- Validação de Estoque: Checagem rigorosa de disponibilidade antes e durante o processamento do pedido.
- Alertas de Interesse: Usuários podem assinar notificações (
POST /alerts) para produtos sem estoque. O sistema dispara e-mails automaticamente via RabbitMQ assim que o produto é reposto.
- Feedback por E-mail: Atualizações de status de pedidos e confirmações de cadastro enviadas via integração SMTP (MailHog em dev).
- Validação de CEP e FRETE: Integração com API externa para garantir a integridade dos endereços de entrega e cálculo de frete.
| Perfil | Acesso Permitido |
|---|---|
| Público | • Visualizar Catálogo (GET /products)• Registro ( POST /users)• Recuperação de Senha • Cadastrar Alerta de Estoque |
| Usuário (USER) | • Realizar Pedidos (POST /orders)• Gerenciar seus Endereços e Alertas • Visualizar histórico de compras |
| Admin (ADMIN) | • Gestão de Catálogo (CRUD Produtos/Categorias) • Gestão de Meios de Pagamento • Gestão de Usuários |
A aplicação utiliza Spring Profiles para alternar comportamentos conforme o ambiente:
- 🟢
dev: (Default) PostgreSQL local, RabbitMQ local e MailHog para simulação de e-mails. - 🔴
prod: Variáveis de ambiente, conexão segura com banco na nuvem. - 🟡
test: Banco H2 em memória para testes de integração ultra-rápidos.
- Docker & Docker Compose (Método Recomendado)
- Ou: Java 21 JDK + Maven + PostgreSQL + RabbitMQ instalados localmente.
Sobe toda a infraestrutura (API, Banco, Broker e Servidor de E-mail) com um comando:
# 1. Clone o repositório
git clone https://github.com/DarkMatter015/server-ecommerce.git
cd server-ecommerce
# 2. Inicie os serviços
docker-compose up --build -d✅ API: http://localhost:8080 | MailHog: http://localhost:8025
Caso queira rodar a aplicação via IDE, mas manter a infraestrutura no Docker:
- Inicie a Infraestrutura:
docker-compose up postgres rabbitmq mailhog -d
- Rode a Aplicação:
./mvnw spring-boot:run
Para facilitar a integração e o teste dos endpoints, disponibilizo duas formas principais de documentação.
A documentação interativa é gerada automaticamente e permite testar requisições diretamente pelo navegador.
👉 Acesso Local: http://localhost:8080/swagger-ui.html
Uma coleção completa do Postman com requisições pré-configuradas está disponível no diretório postman/.
👉 Ver Guia e Download da Coleção
A API segue um contrato estrito de respostas. O tratamento de erros é centralizado (GlobalExceptionHandler), garantindo que o client (Front-end) sempre receba um JSON previsível, mesmo em falhas críticas.
Exemplo de resposta ao criar um recurso (ex: Usuário). O payload retorna os dados públicos da entidade criada.
{
"id": 3,
"active": true,
"displayName": "Lucas Camargo",
"email": "decamargoluk@gmail.com",
"cpf": "11111111111",
"roles": [
{
"id": 2,
"active": true,
"name": "USER"
}
]
}Retornado quando os dados enviados violam as regras do DTO (Bean Validation). O campo validationErrors fornece um mapa detalhado campo: erro para facilitar o feedback no front-end.
{
"timestamp": 1767828796670,
"message": "Campos preenchidos incorretamente.",
"status": 400,
"url": "/users",
"validationErrors": {
"password": "A senha deve conter pelo menos uma letra minuscula, uma maiuscula e um numero.",
"displayName": "O nome de exibicao deve ter entre 3 e 255 caracteres."
}
}Ocorre quando o usuário não está autenticado ou tenta acessar um recurso de ADMIN (como /products POST) sem permissão.
{
"path": "/users/3",
"error": "Unauthorized",
"message": "Authentication credentials are missing or invalid.",
"timestamp": "2026-01-07T23:33:59.396305900Z",
"status": 401
}Para segurança da aplicação, erros internos não expõem o stacktrace Java em produção. Uma mensagem genérica é retornada enquanto o erro real é logado no servidor.
{
"timestamp": 1709664000000,
"message": "Ocorreu um erro interno inesperado. Tente Novamente mais tarde.",
"status": 500,
"url": "/orders"
}A confiabilidade é um pilar deste projeto. Foram implementados Testes de Integração que sobem o contexto do Spring Boot para validar os fluxos de ponta a ponta.
-
Ambiente Isolado: Utiliza banco de dados em memória (H2 Database) para garantir que os testes não impactem os dados de desenvolvimento.
-
Escopo: Validação de regras de negócio, restrições de banco e segurança dos endpoints.
Para executar a suíte de testes:
# Rodar todos os testes
./mvnw test
|
Lucas Matheus de Camargo Desenvolvedor Full Stack | QA 
|