ein wenig aufgeräumt
This commit is contained in:
stefan
@@ -1,355 +0,0 @@
|
||||
# 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](#überblick)
|
||||
- [Architektur & Features](#architektur--features)
|
||||
- [API Endpoints](#api-endpoints)
|
||||
- [Konfiguration](#konfiguration)
|
||||
- [Lokale Entwicklung](#lokale-entwicklung)
|
||||
- [Docker Deployment](#docker-deployment)
|
||||
- [Testing](#testing)
|
||||
- [Monitoring & Health Checks](#monitoring--health-checks)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## 🎯 Ü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
|
||||
```http
|
||||
GET /ping
|
||||
```
|
||||
**Beschreibung**: Einfacher Ping ohne Circuit Breaker
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"status": "pong"
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Enhanced Ping mit Circuit Breaker
|
||||
```http
|
||||
GET /ping/enhanced?simulate=false
|
||||
```
|
||||
**Beschreibung**: Ping mit Circuit Breaker Schutz
|
||||
**Query Parameter**:
|
||||
- `simulate` (optional): `true` für Failure-Simulation
|
||||
|
||||
**Success Response**:
|
||||
```json
|
||||
{
|
||||
"status": "pong",
|
||||
"timestamp": "2025-08-14 12:26:30",
|
||||
"service": "ping-service",
|
||||
"circuitBreaker": "CLOSED"
|
||||
}
|
||||
```
|
||||
|
||||
**Fallback Response** (Circuit Breaker OPEN):
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```http
|
||||
GET /ping/health
|
||||
```
|
||||
**Beschreibung**: Health Check mit Circuit Breaker Status
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"status": "UP",
|
||||
"timestamp": "2025-08-14 12:26:30",
|
||||
"circuitBreaker": "CLOSED"
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Test Failure Endpoint
|
||||
```http
|
||||
GET /ping/test-failure
|
||||
```
|
||||
**Beschreibung**: Endpoint zum Testen der Circuit Breaker Funktionalität (60% Failure Rate)
|
||||
|
||||
## ⚙️ Konfiguration
|
||||
|
||||
### Application Configuration (`application.yml`)
|
||||
```yaml
|
||||
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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Von der Projekt-Root ausführen
|
||||
docker build -t ping-service:latest -f temp/ping-service/Dockerfile .
|
||||
```
|
||||
|
||||
### Run Container
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
./gradlew :temp:ping-service:test
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
```bash
|
||||
./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
|
||||
```bash
|
||||
# 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)
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Consul Status prüfen
|
||||
consul agent -dev
|
||||
|
||||
# Oder Service ohne Consul starten
|
||||
spring.cloud.consul.discovery.enabled=false
|
||||
```
|
||||
|
||||
#### 4. Docker Build Fails
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Debug Mode aktivieren
|
||||
DEBUG=true ./gradlew :temp:ping-service:bootRun
|
||||
|
||||
# Debug Port: 5005
|
||||
```
|
||||
|
||||
### Logs
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user