🏗️ toBusiness — Microservice Template (Java + Spring Boot)

Este repositório serve como boilerplate base para os microserviços da plataforma toBusiness, totalmente construído em Java 21 com Spring Boot 3.3, utilizando PostgreSQL como banco de dados e Kafka como sistema de mensageria.

O objetivo é garantir padronização estrutural, modularidade e facilidade de escalar novos microsserviços seguindo o mesmo padrão arquitetural.

---

🚀 Stack Tecnológica

Camada	Tecnologia	Descrição
Linguagem	Java 21	Base da aplicação
Framework	Spring Boot 3.3	Estrutura principal do microserviço
Banco de Dados	PostgreSQL 15	Armazenamento relacional
Mensageria	Apache Kafka 7.4.3 (Confluent)	Comunicação assíncrona entre microsserviços
Coordenação	Zookeeper 7.4.3	Gerenciamento de brokers Kafka
Observabilidade	Kafdrop 4.2.0	Interface web para inspecionar tópicos Kafka
Infraestrutura	Docker & Docker Compose	Orquestração de containers

---

🧱 Estrutura de Pastas

microservice-template/
├── src/
│   ├── main/
│   │   ├── java/com/tobusiness/microservice_template/
│   │   │   ├── controller/        # Camada REST (endpoints)
│   │   │   ├── service/           # Lógica de negócio
│   │   │   ├── repository/        # Acesso ao banco via JPA
│   │   │   ├── model/             # Entidades (Models)
│   │   │   ├── dto/               # Objetos de transporte
│   │   │   ├── exception/         # Exceções customizadas
│   │   │   ├── handler/           # Tratamento global de erros
│   │   │   └── MicroserviceTemplateApplication.java
│   │   └── resources/
│   │       ├── application.yml    # Configurações principais
│   │       └── logback.xml
├── Dockerfile
├── docker-compose.yml
├── pom.xml
└── README.md

---

⚙️ Configuração do Projeto

🧩 Dependências Principais (pom.xml)

• spring-boot-starter-web
• spring-boot-starter-data-jpa
• spring-boot-starter-validation
• spring-kafka
• postgresql
• lombok
• spring-boot-starter-test

---

🧠 Padrão Arquitetural (MVC)

Camada	Responsabilidade
Controller	Expor endpoints REST
Service	Regras de negócio e orquestração
Repository	Operações JPA com o banco
Model (Entity)	Representação das tabelas do banco
DTOs	Transporte de dados (entrada/saída)
Exception + Handler	Tratamento centralizado de erros

---

🧩 Exemplo — Entidade User

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "id_user")
    private Long id;

    @Column(name = "uuid_user", columnDefinition = "UUID DEFAULT gen_random_uuid()", updatable = false, unique = true)
    private UUID uuid;

    @Column(name = "name_user", nullable = false)
    private String name;

    @Column(name = "email_user", nullable = false, unique = true)
    private String email;

    @Column(name = "password_user", nullable = false)
    private String password;

    @CreationTimestamp
    @Column(name = "created_at_user", columnDefinition = "TIMESTAMPTZ", updatable = false)
    private OffsetDateTime createdAt;

    @UpdateTimestamp
    @Column(name = "updated_at_user", columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime updatedAt;

    @Column(name = "deleted_at_user", columnDefinition = "TIMESTAMPTZ")
    private OffsetDateTime deletedAt;
}

---

🧰 Docker Compose — Infraestrutura Completa

services:
  postgres:
    image: postgres:15
    container_name: postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: tobusiness
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    networks:
      - tobusiness_net

  zookeeper:
    image: confluentinc/cp-zookeeper:7.4.3
    container_name: zookeeper
    networks:
      - tobusiness_net
    environment:
      ZOOKEEPER_CLIENT_PORT: 2181
      ZOOKEEPER_TICK_TIME: 2000

  kafka:
    image: confluentinc/cp-kafka:7.4.3
    container_name: kafka
    networks:
      - tobusiness_net
    depends_on:
      - zookeeper
    ports:
      - "9092:9092"
    environment:
      KAFKA_BROKER_ID: 1
      KAFKA_ZOOKEEPER_CONNECT: zookeeper:2181
      KAFKA_LISTENERS: PLAINTEXT://0.0.0.0:9092
      KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092
      KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: PLAINTEXT:PLAINTEXT
      KAFKA_INTER_BROKER_LISTENER_NAME: PLAINTEXT
      KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1

  kafdrop:
    image: obsidiandynamics/kafdrop:4.2.0
    container_name: kafdrop
    networks:
      - tobusiness_net
    depends_on:
      - kafka
    ports:
      - "19000:9000"
    environment:
      KAFKA_BROKERCONNECT: kafka:9092
      SERVER_PORT: 9000

  app:
    build: .
    container_name: microservice-template
    depends_on:
      - postgres
      - kafka
    environment:
      SPRING_PROFILES_ACTIVE: dev
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/tobusiness
      SPRING_DATASOURCE_USERNAME: postgres
      SPRING_DATASOURCE_PASSWORD: postgres
      SPRING_KAFKA_BOOTSTRAP_SERVERS: kafka:9092
    ports:
      - "8080:8080"
    networks:
      - tobusiness_net

networks:
  tobusiness_net:
    driver: bridge

volumes:
  pg_data:

---

🐘 Banco de Dados e JPA

O Hibernate está configurado para criar/atualizar as tabelas automaticamente com base nas entidades Java:

spring:
  datasource:
    url: jdbc:postgresql://postgres:5432/tobusiness
    username: postgres
    password: postgres
  jpa:
    hibernate:
      ddl-auto: update   # cria/atualiza tabelas automaticamente
    show-sql: true
    properties:
      hibernate:
        format_sql: true

⚡ Subindo o Ambiente

1️⃣ Clonar o repositório

git clone https://github.com/seuusuario/microservice-template.git
cd microservice-template

2️⃣ Construir e subir os containers

docker compose up -d --build

3️⃣ Verificar se os serviços estão rodando

docker ps

Você deverá ver:

postgres, zookeeper, kafka, kafdrop, microservice-template

---

🌐 Endpoints da API

Método	Endpoint	Descrição
GET	/api/users	Lista todos os usuários
GET	/api/users/{uuid}	Busca um usuário específico
POST	/api/users	Cria um novo usuário
DELETE	/api/users/{uuid}	Realiza soft delete (marca como excluído)

---

🔍 Monitoramento do Kafka

• Kafdrop UI: http://localhost:19000
• Broker Kafka interno: kafka:9092

---

🧠 Comandos Úteis

Ação	Comando
Subir o ambiente	docker compose up -d --build
Parar os containers	docker compose down
Ver logs do app	docker logs -f microservice-template
Acessar o banco	docker exec -it postgres psql -U postgres tobusiness
Acessar container do app	docker exec -it microservice-template bash

---

✅ Status Final do Ambiente

Serviço	Porta	Status Esperado
Spring Boot App	8080	✅ Rodando
PostgreSQL	5432	✅ Conectado
Kafka Broker	9092	✅ Pronto
Zookeeper	2181	✅ Ativo
Kafdrop UI	19000	✅ Acessível

👨‍💻 Autor

Rodrigo Pretes
Desenvolvedor Back-End • Engenheiro de Computação
📍 Belo Horizonte - MG
💼 LinkedIn

---

Este repositório serve como template padrão para todos os microserviços do ecossistema toBusiness, desenvolvido com foco em escalabilidade, modularidade e interoperabilidade entre serviços via mensageria Kafka.