mocode-software/meldestelle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9c21154199
meldestelle/temp/README_TEMP.md
stefan d937e82d2b refactoring(ping-service) 
TODO-Roadmap.md
2025-08-14 12:30:31 +02:00

8.8 KiB
Raw Blame History

Ping Service - Circuit Breaker Demo

⚠️ Wichtiger Hinweis

Dieses Modul (:temp:ping-service) ist ein temporärer Service ausschließlich für Testzwecke. Seine Aufgabe ist die Validierung der technischen Infrastruktur im Rahmen des "Tracer Bullet"-Szenarios und die Demonstration von Circuit Breaker Patterns.

Nachdem der End-to-End-Test erfolgreich war, sollte dieses Modul in der settings.gradle.kts wieder deaktiviert oder vollständig entfernt werden.

📋 Inhaltsverzeichnis

🎯 Überblick

Der ping-service ist ein Spring Boot Microservice, der die grundlegende Service-Architektur und moderne Resilience Patterns demonstriert:

  • Circuit Breaker Pattern mit Resilience4j
  • Service Discovery mit Spring Cloud Consul
  • Health Checks und Monitoring mit Spring Boot Actuator
  • Containerisierte Deployment mit optimiertem Docker Setup
  • Comprehensive Testing mit Integration- und Unit-Tests

🏗️ Architektur & Features

Technology Stack

  • Spring Boot 3.2.5 - Modern Java/Kotlin web framework
  • Kotlin - Primary programming language
  • Resilience4j - Circuit breaker and fault tolerance
  • Spring Cloud Consul - Service discovery and configuration
  • Micrometer + Prometheus - Metrics collection
  • Docker - Containerization with multi-stage builds

Circuit Breaker Configuration

Der Service verwendet Resilience4j Circuit Breaker mit folgenden Einstellungen:

  • Failure Rate Threshold: 60% (Circuit öffnet bei 60% Fehlern)
  • Minimum Calls: 4 (Mindestanzahl Calls für Berechnung)
  • Wait Duration: 5s (Wartezeit im OPEN Status)
  • Half-Open Calls: 3 (Anzahl Calls im HALF_OPEN Status)

🚀 API Endpoints

1. Standard Ping Endpoint

GET /ping

Beschreibung: Einfacher Ping ohne Circuit Breaker Response:

{
  "status": "pong"
}

2. Enhanced Ping mit Circuit Breaker

GET /ping/enhanced?simulate=false

Beschreibung: Ping mit Circuit Breaker Schutz Query Parameter:

  • simulate (optional): true für Failure-Simulation

Success Response:

{
  "status": "pong",
  "timestamp": "2025-08-14 12:26:30",
  "service": "ping-service",
  "circuitBreaker": "CLOSED"
}

Fallback Response (Circuit Breaker OPEN):

{
  "status": "fallback",
  "message": "Service temporarily unavailable",
  "timestamp": "2025-08-14 12:26:30",
  "service": "ping-service-fallback",
  "circuitBreaker": "OPEN",
  "error": "Simulated service failure"
}

3. Health Check Endpoint

GET /ping/health

Beschreibung: Health Check mit Circuit Breaker Status

Response:

{
  "status": "UP",
  "timestamp": "2025-08-14 12:26:30",
  "circuitBreaker": "CLOSED"
}

4. Test Failure Endpoint

GET /ping/test-failure

Beschreibung: Endpoint zum Testen der Circuit Breaker Funktionalität (60% Failure Rate)

⚙️ Konfiguration

Application Configuration (application.yml)

spring:
  application:
    name: ping-service
  cloud:
    consul:
      host: localhost
      port: 8500
      discovery:
        register: true
        health-check-path: /actuator/health
        health-check-interval: 10s

server:
  port: 8082

management:
  endpoints:
    web:
      exposure:
        include: health,info,circuitbreakers
  endpoint:
    health:
      show-details: always

resilience4j:
  circuitbreaker:
    instances:
      pingCircuitBreaker:
        failure-rate-threshold: 60
        minimum-number-of-calls: 4
        wait-duration-in-open-state: 5s
        permitted-number-of-calls-in-half-open-state: 3

Environment Variables

  • SPRING_PROFILES_ACTIVE: Aktives Spring Profil (default: default)
  • DEBUG: Enable Debug-Modus (true/false, Debug Port: 5005)
  • SERVER_PORT: Server Port (default: 8082)

💻 Lokale Entwicklung

Prerequisites

  • Java 21+
  • Docker (optional)
  • Consul (für Service Discovery)

Service starten

# Standard Start
./gradlew :temp:ping-service:bootRun

# Mit spezifischem Profil
./gradlew :temp:ping-service:bootRun -Pspring.profiles.active=dev

# Build JAR
./gradlew :temp:ping-service:bootJar

Service testen

# Standard Ping
curl http://localhost:8082/ping

# Enhanced Ping
curl http://localhost:8082/ping/enhanced

# Health Check
curl http://localhost:8082/ping/health

# Circuit Breaker mit Simulation
curl "http://localhost:8082/ping/enhanced?simulate=true"

# Failure Test
curl http://localhost:8082/ping/test-failure

🐳 Docker Deployment

Build Docker Image

# Von der Projekt-Root ausführen
docker build -t ping-service:latest -f temp/ping-service/Dockerfile .

Run Container

# Standard Mode
docker run -p 8082:8082 ping-service:latest

# Debug Mode
docker run -p 8082:8082 -p 5005:5005 -e DEBUG=true ping-service:latest

# Mit Environment Variables
docker run -p 8082:8082 \
  -e SPRING_PROFILES_ACTIVE=prod \
  -e LOGGING_LEVEL_ROOT=WARN \
  ping-service:latest

Docker Features

  • Multi-stage Build für optimale Image-Größe
  • Non-root User für bessere Sicherheit
  • Health Checks integriert
  • JVM Optimierungen für Container-Umgebung
  • Debug Support über Environment Variables

🧪 Testing

Unit Tests ausführen

./gradlew :temp:ping-service:test

Integration Tests

./gradlew :temp:ping-service:integrationTest

Test Coverage

Der Service enthält umfassende Tests für:

  • Controller Tests: API Endpoint Validierung
  • Circuit Breaker Tests: Resilience4j Integration
  • Integration Tests: End-to-End Scenarios
  • Health Check Tests: Actuator Endpoint Validation

Test Klassen

  • PingControllerTest: Controller Unit Tests
  • PingControllerIntegrationTest: Full Spring Context Tests
  • PingServiceCircuitBreakerTest: Circuit Breaker Logic Tests

📊 Monitoring & Health Checks

Actuator Endpoints

  • Health: GET /actuator/health
  • Health Readiness: GET /actuator/health/readiness
  • Health Liveness: GET /actuator/health/liveness
  • Info: GET /actuator/info
  • Circuit Breakers: GET /actuator/circuitbreakers
  • Metrics: GET /actuator/metrics
  • Prometheus: GET /actuator/prometheus

Circuit Breaker Monitoring

# Circuit Breaker Status
curl http://localhost:8082/actuator/circuitbreakers

# Metrics
curl http://localhost:8082/actuator/metrics/resilience4j.circuitbreaker.calls

# Prometheus Format
curl http://localhost:8082/actuator/prometheus | grep circuit

Service Discovery

Bei aktiviertem Consul wird der Service automatisch registriert:

  • Service Name: ping-service
  • Health Check: /actuator/health
  • Check Interval: 10 Sekunden

🔧 Troubleshooting

Häufige Probleme

1. Service startet nicht (Port bereits belegt)

# Port prüfen
netstat -tlnp | grep 8082

# Alternativen Port verwenden
SERVER_PORT=8083 ./gradlew :temp:ping-service:bootRun

2. Circuit Breaker öffnet nicht

  • Mindestens 4 Calls erforderlich (siehe minimum-number-of-calls)
  • 60% Failure Rate erforderlich
  • Verwende /ping/test-failure für Tests

3. Consul Connection Failed

# Consul Status prüfen
consul agent -dev

# Oder Service ohne Consul starten
spring.cloud.consul.discovery.enabled=false

4. Docker Build Fails

# Build Context prüfen - muss von Projekt-Root ausgeführt werden
docker build -t ping-service:test -f temp/ping-service/Dockerfile .

# Nicht von temp/ping-service/ ausführen!

Debug Mode

# Debug Mode aktivieren
DEBUG=true ./gradlew :temp:ping-service:bootRun

# Debug Port: 5005

Logs

# Alle Logs
docker logs <container-id>

# Circuit Breaker Logs
docker logs <container-id> 2>&1 | grep -i circuit

# Health Check Logs
docker logs <container-id> 2>&1 | grep -i health

📝 Entwicklungsnotizen

Warum Circuit Breaker?

Der Circuit Breaker Pattern verhindert:

  • Cascade Failures: Verhindert Ausfall-Kaskaden
  • Resource Exhaustion: Schont Ressourcen bei Service-Problemen
  • Fast Failure: Schnelle Fehlerrückmeldung statt lange Timeouts

Fallback Strategy

Bei OPEN Circuit Breaker:

  • Sofortige Fallback-Response (keine Latenz)
  • Informative Fehlermeldungen
  • Status-Informationen für Debugging

Production Readiness

  • Health Checks für Kubernetes/Docker
  • Prometheus Metriken für Monitoring
  • Non-root Container für Sicherheit
  • Optimierte JVM Settings für Container

Letzte Aktualisierung: 2025-08-14 Version: 1.0.0 Maintainer: Meldestelle Development Team