🤸‍♂️ Minha Jornada Criando uma API RESTful para Academia de ginástica

#Java
#Spring

🎯 Por que uma API de academia de ginástica?

Sempre gostei de aprender na prática. Para mim, a melhor forma de consolidar conceitos é aplicando-os em um projeto real, enfrentando os desafios e ajustando o rumo conforme surgem obstáculos. Foi assim que nasceu a Academia GYM--API: um projeto que começou como um exercício proposto na Spring Framework Experience e acabou se transformando em um divisor de águas na minha jornada como desenvolvedor Java.

A ideia era relativamente simples: criar uma API que permitisse gerenciar uma academia de ginástica, com funcionalidades como cadastro de alunos, planos de treino, controle de instrutores e acompanhamento da própria academia. No entanto, o que parecia ser apenas mais um desafio técnico rapidamente se tornou uma imersão profunda em boas práticas, arquitetura de software e ferramentas que são essenciais no dia a dia de qualquer desenvolvedor back-end.

📚 O Contexto que Me Motivou

O ponto de partida foi o desafio final da Digital Innovation One (DIO) no curso Spring Framework Experience. O objetivo: construir uma API RESTful para gerenciar os dados de uma academia de ginástica. Esse desafio me chamou atenção porque unia dois pontos importantes: era prático, exigia aplicação de conceitos modernos, e ao mesmo tempo tinha um escopo próximo ao de sistemas reais que encontramos no mercado.

Eu já tinha familiaridade com o Java e tinha acabado de aprender sobre o Spring Boot, mas nunca tinha levado um projeto do zero até um nível mais próximo de produção. Foi exatamente isso que me motivou: a oportunidade de sair do terreno seguro dos exemplos simples e mergulhar em um projeto mais robusto, onde eu precisaria pensar em camadas, regras de negócio e validações.

🛠 As Tecnologias Escolhidas

Para construir a aplicação, optei por uma stack que equilibrasse simplicidade no desenvolvimento e relevância no mercado:

Java 17 (LTS): versão estável e moderna da linguagem.
Spring Boot 3.2.5: o coração do projeto, oferecendo simplicidade e poder para estruturar a API.
Spring Data JPA: abstração prática para persistência em banco de dados.
Spring Boot Actuator: monitoramento e métricas em tempo real da aplicação, facilitando observabilidade e manutenção.
H2 Database: banco de dados em memória, perfeito para desenvolvimento rápido e testes.
Maven: para gerenciar dependências e build.
Bean Validation: validações declarativas e poderosas para garantir qualidade dos dados.

A escolha do H2 foi fundamental: ele me permitiu focar no desenvolvimento da lógica da aplicação sem perder tempo configurando bancos de dados externos. Bastava rodar a aplicação e já tinha um console acessível para validar consultas e verificar a persistência. Essa agilidade foi essencial para não me perder em detalhes antes da hora.

⚡ O Problema Principal Enfrentado

Se tem algo que me fez “ralar” neste projeto, foi a modelagem dos relacionamentos entre entidades no JPA. Logo de início, me deparei com três problemas recorrentes:

Referências circulares: quando um Aluno tinha referência a um Treino, que por sua vez se relacionava com um Instrutor, e isso acabava gerando ciclos infinitos na serialização.
Lazy vs. Eager Loading: entender quando buscar dados imediatamente e quando carregar sob demanda foi essencial para não impactar a performance.
Serialização JSON infinita: ao expor entidades diretamente, era comum cair em loops sem fim na hora de transformar em JSON.

A solução veio com uma combinação de estratégias:

Utilizar @JsonIgnore em pontos críticos para evitar loops.
Configurar relacionamentos com FetchType.LAZY para não carregar mais dados do que o necessário.
Criar DTOs em alguns casos para expor apenas o que fazia sentido ao cliente da API.

Esse aprendizado foi crucial: percebi que modelar entidades não é apenas criar classes e relacionamentos, mas sim pensar em como esses dados serão usados e transportados pela aplicação.

🔍 A Descoberta das Validações Bean

Outro ponto que agregou muito valor ao projeto foi a implementação de validações com Bean Validation. Até então, eu costumava verificar regras manualmente dentro dos métodos, o que deixava o código verboso e sujeito a inconsistências. Com o Bean Validation, percebi que é possível centralizar as regras de negócio diretamente no modelo, tornando o código mais limpo e fácil de manter.

Exemplo prático:

@NotBlank(message = "Nome é obrigatório")
@Size(min = 2, max = 100, message = "Nome deve ter entre 2 e 100 caracteres")
private String nome;

@Email(message = "Email deve ser válido")
@NotBlank(message = "Email é obrigatório")
private String email;

Essas anotações garantem que os dados cheguem na aplicação já validados, poupando tempo de debug e prevenindo falhas graves. A API se torna mais robusta, pois impede que informações inválidas sequer cheguem ao banco de dados.

🎯 O Momento "Eureka" - Exception Handler Global

Um dos maiores “pulos de qualidade” foi quando implementei um Exception Handler global. Até então, erros eram tratados de forma pontual em cada endpoint, o que gerava respostas inconsistentes. Com o uso do @ControllerAdvice, consegui padronizar o tratamento de erros em toda a API.

@ControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
  
  @ExceptionHandler(BadRequestException.class)
  public ResponseEntity<ErrorResponse> handleBadRequest(BadRequestException ex) {
      ErrorResponse error = new ErrorResponse("BAD_REQUEST", ex.getMessage());
      return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(error);
  }
}

Essa abordagem elevou a API a outro nível: de uma aplicação experimental para uma solução mais próxima de um produto real, com mensagens claras e consistentes para os clientes que a consumirem.

📊 Os Resultados Obtidos

Ao concluir a primeira versão da Academia API, pude observar resultados bem concretos:

✅ 5 entidades principais modeladas (Aluno, Instrutor, Plano, Treino e Academia)
✅ Mais de 20 endpoints funcionando de forma RESTful
✅ Validações robustas aplicadas em todos os campos
✅ Tratamento global de exceções
✅ Documentação clara no README
✅ Logs estruturados do Hibernate para debug
✅ Console H2 integrado para consultas e testes rápidos

Essa lista não representa apenas entregas técnicas, mas também habilidades adquiridas e confiança para enfrentar projetos maiores.

🌟 Insights e Aprendizados Principais

1. Arquitetura em Camadas é indispensável

Manter separação clara entre Controllers, Models, Services, Exceptions e Repositories não é exagero: é o que garante organização e testabilidade.

2. Spring Boot realmente entrega produtividade

O conceito de “convenção sobre configuração” fez muito sentido na prática. Com poucas linhas de configuração, já tinha uma aplicação robusta em funcionamento.

3. Validações economizam tempo

Implementar validações desde o início evitou erros silenciosos e dados inconsistentes no banco.

4. Ferramentas simples fazem diferença

O H2, apesar de simples, foi uma das melhores escolhas para acelerar o desenvolvimento.

🔮 Próximos Passos no Meu Aprendizado

A Academia API cumpriu seu papel: foi um projeto de prática que me permitiu explorar conceitos fundamentais do ecossistema Spring Boot. Não tenho planos de evoluí-lo além do que já foi desenvolvido, mas a experiência abriu caminho para novos focos de estudo.

Meus próximos passos no aprendizado serão:

Curto Prazo

Me aprofundar em bancos de dados relacionais
Estudar JDBC e entender como funciona a comunicação direta com o banco
Explorar boas práticas de design e padrões de arquitetura em APIs

Médio e Longo Prazo

Entender estratégias de persistência em produção (PostgreSQL, MySQL)
Aprender mais sobre otimização de queries e performance em APIs
Conhecer mais sobre ferramentas de documentação e testes (Swagger, Postman)
Praticar mais sobre segurança em APIs (autenticação e autorização)

💡 Dicas Para Quem Quer Começar

Se você também está começando a explorar o Spring Boot e deseja criar sua primeira API, deixo algumas recomendações práticas:

Comece pequeno: use H2 e Starters para não complicar.
Valide sempre: aplique Bean Validation desde o início.
Trate exceções: um @ControllerAdvice vai salvar seu projeto.
Documente tudo: um bom README facilita sua vida e a de quem for usar seu código.
Não subestime os logs: entender como o Hibernate se comporta é fundamental.

📈 O Impacto no Meu Crescimento

Mais do que entregar uma API, esse projeto trouxe impacto direto no meu crescimento:

Confiança: agora me sinto preparado para estruturar APIs do zero.
Domínio: aprendi a lidar melhor com o ecossistema Spring.
Portfólio: o projeto é uma vitrine real de minhas habilidades.
Visão: abriu portas para pensar em soluções mais complexas e escaláveis.

🤝 Como Você Pode Contribuir

A AcademiaGYM -- API está disponível como open source no GitHub!

Você pode:

⭐ Dar um star no repositório
🐛 Reportar bugs ou sugerir melhorias
🔨 Contribuir com código
📖 Ajudar na documentação
💡 Sugerir novas features

Link do projeto: AcademiaGYM-API

🎉 Conclusão e Reflexões Finais

Construir a Academia API foi muito mais do que escrever código. Foi uma jornada de aprendizado prático sobre:

Arquitetura limpa e organizada
Boas práticas de APIs RESTful
Validações e segurança de dados
Tratamento de erros estruturado
Força do ecossistema Spring Boot

Essa experiência me mostrou que aprender programação vai além de seguir tutoriais: é preciso colocar a mão na massa, enfrentar problemas e buscar soluções. O que parecia só mais um desafio virou um marco no meu portfólio e um reforço de que estou no caminho certo.

Lembre-se: todo expert já foi iniciante. O importante é começar, errar, corrigir e evoluir. 🚀