An open source product catalog API built chapter by chapter: layered architecture, automated tests, OAuth2 security, domain modeling and data access with Java and Spring Boot.
O ASJCatalog é a API de um catálogo de produtos construída em Java e Spring Boot. O nome vem das iniciais de Albert Silva de Jesus: o projeto nasceu da base do DSCatalog, do curso DevSuperior, e evoluiu de forma independente até se tornar praticamente outro projeto.
É um projeto open source e sem fins comerciais: um laboratório de aprendizado, uma fonte de consulta para o futuro e um material para ajudar desenvolvedores júnior. A evolução é contada em capítulos, um por branch, cada um publicado no LinkedIn.
📖 Documentação técnica · 🚀 Primeiros Passos · 🗂️ Issues · 🎯 Pronto para produção · 🤝 Contribuir · 📊 Relatório JaCoCo
- Listagem de produtos sem N+1: paginação numa consulta nativa e carregamento das categorias numa segunda consulta com
JOIN FETCH. → DATA-ACCESS - OAuth2 com JWT: Authorization Server e Resource Server na mesma aplicação, com access token JWT, refresh token com rotação e controle de acesso por roles. → AUTHENTICATION
- Fluxos de conta com e-mail: cadastro, ativação, recuperação e redefinição de senha, com e-mails HTML gerados pelo Thymeleaf. → ACCOUNT-FLOWS
- Internacionalização: mensagens da API em português do Brasil, inglês e espanhol, escolhidas pelo cabeçalho
Accept-Language. → INTERNATIONALIZATION - Suíte de testes em duas fases: testes de unidade no Surefire e testes de integração (
*IT) no Failsafe, todos executados com./mvnw verify. → TESTING - Cobertura medida e exigida no build: o JaCoCo gera relatórios dos testes de unidade, de integração e dos dois juntos; o consolidado cobre 96% das linhas e 92% dos branches, e o build falha se a cobertura cair abaixo do limite mínimo. → TESTING · Relatório publicado
- Decisões técnicas registradas: contexto, motivo, alternativas e consequências das principais escolhas do projeto. → DESIGN-DECISIONS
Cada capítulo fica em uma branch própria, com um README que apresenta o que foi construído naquela etapa.
| Nº | Tema | Branch | Resumo |
|---|---|---|---|
| 01 | Operações CRUD com Spring Boot | chapter-01-crud |
CRUD de produtos e categorias em arquitetura em camadas, com DTOs (records), mappers, paginação e tratamento global de exceções. |
| 02 | Testes automatizados no back-end | chapter-02-tests |
Testes de unidade, de repositório e da camada web com JUnit 5, Mockito e MockMvc, usando factories e foco em testabilidade. |
| 03 | Validação e segurança (OAuth2 | JWT) | chapter-03-validation-security |
Spring Security 6 com Authorization Server e Resource Server, JWT, controle de acesso por roles e Bean Validation. |
| 04 | Domínio, ORM, casos de uso e acesso a dados | chapter-04-domain-orm |
Ciclo de vida completo da conta com e-mails transacionais, JPQL e SQL nativo, solução do N+1 e domínio em módulos inspirados em DDD. |
| 05 | Cobertura de testes com JaCoCo | chapter-05-jacoco |
Cobertura dos testes de unidade e de integração com JaCoCo, limite mínimo de cobertura no build e revisão da qualidade de toda a suíte de testes. |
| Branch | O que contém |
|---|---|
develop |
O projeto completo e atualizado (capítulo 05), com a documentação técnica em docs/. É nela que o trabalho acontece e para ela que vão os Pull Requests. |
main |
Esta página de entrada. Recebe o código do projeto apenas no deploy final; a pasta backend/ daqui é, por enquanto, só o esqueleto inicial. |
chapter-* |
O registro de cada capítulo, como foi publicado. |
Os guias do backend (primeiros passos, configuração, arquitetura, domínio, acesso a dados, endpoints, autenticação, testes, convenções e decisões técnicas), o contrato de segurança e o histórico de auditorias estão reunidos no Índice da Documentação, na branch develop.
O frontend do ASJCatalog é independente e fica em outro repositório: asjcatalog-frontend.
- Falta um capítulo para encerrar a evolução do projeto: Docker e CI/CD. Ele será publicado em uma nova branch.
- As melhorias pendentes estão registradas como issues. As necessárias para colocar a API em produção estão no milestone Pronto para produção.
Qualquer pessoa pode contribuir, inclusive quem está começando. Escolha uma issue (as marcadas com good first issue são um bom ponto de partida), crie sua branch a partir da develop e abra o Pull Request para a develop.
O passo a passo completo está no CONTRIBUTING.md. Ao participar, siga o Código de Conduta.
Distribuído sob a licença MIT. Veja o arquivo LICENSE.
Albert Silva de Jesus
Desenvolvedor Backend Java | Spring Boot
