Todo API

O que é

Esta é uma API RESTful de tarefas (to-do) desenvolvida com Spring Boot 4, Java 21 e arquitetura em camadas. O projeto serve como exemplo de backend que gerencia tarefas pendentes, com persistência em PostgreSQL, cache Redis e integração de métricas via Micrometer/Datadog.

Contexto do projeto

O objetivo é oferecer uma API de gerenciamento de tarefas simples e extensível, com foco em:

• Camadas separadas de domínio, aplicação e infraestrutura
• Boas práticas de DDD e Clean Architecture
• Integração com JPA/Hibernate e PostgreSQL
• Métricas e telemetria com Micrometer e Datadog
• Testes com JUnit 5, Testcontainers e Instancio
• Suporte a devcontainer para desenvolvimento isolado

Arquitetura

A estrutura de pacotes reflete a divisão lógica do projeto:

• application: casos de uso, portas de entrada e saída, exceções de negócio
• domain: modelos de domínio e serviços de regras de negócio
• infrastructure: adaptadores de entrada/saída, mapeadores e configurações do framework

Fluxo de chamada principal:

1. TaskController recebe a requisição HTTP
2. Converte DTO para domínio via TaskMapper
3. Chama ManageTaskUseCase para executar regras de negócio
4. TaskPersistenceAdapter persiste dados usando SpringDataTaskRepository
5. A resposta é convertida de volta em TaskResponse

Componentes-chave

• TaskController: API REST em /api/v1/tasks
• ManageTaskUseCase: lógica de criação, atualização, conclusão, reabertura, listagem e estatísticas
• TaskPersistenceAdapter: adaptador JPA para persistência de tarefas
• TaskMapper: mapstruct para conversão entre domínio, entidade e DTO
• application.yaml: configuração de banco, Redis, métricas e actuator

Como funciona

A API expõe operações CRUD para tarefas e endpoints de estatísticas. O controlador também aplica cache para listagem e métricas de contagem.

Principais endpoints:

• POST /api/v1/tasks — cria uma tarefa
• GET /api/v1/tasks — lista todas as tarefas
• GET /api/v1/tasks?completed=true|false — filtra tarefas por status
• PUT /api/v1/tasks/{id} — atualiza título e descrição
• PATCH /api/v1/tasks/{id}/complete — marca como concluída
• PATCH /api/v1/tasks/{id}/reopen — reabre tarefa
• DELETE /api/v1/tasks/{id} — remove tarefa
• GET /api/v1/tasks/stats — retorna estatísticas de tarefas

A configuração de banco de dados e cache é baseada em variáveis de ambiente, definidas no arquivo .env.

Como rodar

Pré-requisitos

• Java 21
• Docker (para serviços e testes com Testcontainers)
• Maven (ou use o wrapper ./mvnw)

Executar localmente

1. Copie ou verifique o arquivo .env na raiz do projeto
2. Inicie os serviços necessários:

docker compose up -d postgres redis datadog-agent

3. Execute a aplicação:

./mvnw spring-boot:run

4. A API ficará disponível em http://localhost:8080

Compilar e empacotar

./mvnw clean package

Como testar

Testes unitários e de integração

./mvnw test

Teste específico de persistência

./mvnw -Dtest=TaskPersistenceAdapterTest test

Observação: os testes de integração usam Testcontainers e requerem Docker para criar um PostgreSQL temporário.

Abrir em Devcontainer

O projeto já possui configuração de devcontainer em .devcontainer/devcontainer.json.

Passos

1. Abra o projeto no VS Code
2. Use o comando Remote-Containers: Reopen in Container ou Dev Containers: Reopen in Container
3. O devcontainer usa o serviço app definido em docker-compose.yaml e a imagem Docker criada a partir de .devcontainer/Dockerfile
4. No terminal do container, execute:

./mvnw spring-boot:run

O ambiente preconfigurado inclui:

• Java 21
• Maven 3.9
• Datadog Java agent
• Extensões recomendadas para Java, Spring Boot, Lombok e SonarLint

Notas finais

• A configuração do docker-compose.yaml também inclui serviços postgres, redis e datadog-agent.
• Use a porta padrão 8080 para a aplicação e 5432 para o PostgreSQL local.
• Ajuste as variáveis de ambiente no .env conforme necessário para seu ambiente de desenvolvimento.