122 lines
4.4 KiB
Markdown
122 lines
4.4 KiB
Markdown
---
|
|
type: Reference
|
|
status: ACTIVE
|
|
owner: Backend Developer
|
|
tags: [backend, service, reference, ping]
|
|
last_update: 2026-04-03
|
|
---
|
|
|
|
# 🎯 Ping Service Reference
|
|
|
|
Der `ping-service` ist der **"Tracer Bullet"** (Leuchtspurgeschoss) der Meldestelle-Architektur. Er ist kein Wegwerf-Prototyp, sondern die **Referenzimplementierung** für alle zukünftigen Microservices.
|
|
|
|
## 1. Mission & Verantwortung
|
|
|
|
* **Technischer Durchstich:** Beweist, dass die Kette *Frontend -> Gateway -> Service -> DB* funktioniert.
|
|
* **Blueprint:** Definiert Standards für Architektur (DDD/Hexagonal), Testing, Security und Build-Prozesse.
|
|
* **Infrastruktur-Validierung:** Testet die Integration mit Consul, Keycloak, Postgres, Redis und Zipkin.
|
|
* **Offline-First Lab:** Hier wird die Delta-Sync-Logik (`/sync`) entwickelt und validiert, bevor sie in fachliche Services einzieht.
|
|
|
|
---
|
|
|
|
## 2. Technologie-Stack
|
|
|
|
* **Framework:** Spring Boot 3.5.x (Spring MVC, Tomcat).
|
|
* **Sprache:** Kotlin 2.x (Coroutines für asynchrone Abläufe).
|
|
* **Datenbank:** PostgreSQL (via Spring Data JPA).
|
|
* **Migration:** Flyway (mit service-spezifischer Historientabelle `flyway_schema_history_ping`).
|
|
* **Security:** OAuth2 Resource Server (JWT via Keycloak).
|
|
* **Resilience:** Resilience4j (Circuit Breaker).
|
|
* **API Contract:** KMP-Modul `:contracts:ping-api` (Shared Code mit Frontend).
|
|
|
|
---
|
|
|
|
## 3. Architektur (Hexagonal)
|
|
|
|
Der Service folgt strikt der **Ports & Adapters** (Hexagonal) Architektur:
|
|
|
|
1. **Domain (`at.mocode.ping.domain`):**
|
|
* Der Kern. Enthält Entities (`Ping`) und Business-Regeln.
|
|
* Frei von Frameworks (kein Spring, kein JPA).
|
|
* Definiert Interfaces für Ports (`PingRepository`).
|
|
|
|
2. **Application (`at.mocode.ping.application`):**
|
|
* Orchestriert die Use Cases (`PingUseCase`).
|
|
* Steuert Transaktionen (`@Transactional`).
|
|
* Verbindet Domain und Infrastructure.
|
|
|
|
3. **Infrastructure (`at.mocode.ping.infrastructure`):**
|
|
* **Web:** `PingController` (REST API).
|
|
* **Persistence:** `PingRepositoryAdapter` (JPA Implementierung).
|
|
* **Security:** Global Config für JWT-Validierung.
|
|
|
|
---
|
|
|
|
## 4. API Endpunkte
|
|
|
|
| Methode | Pfad | Auth | Beschreibung |
|
|
| :--- | :--- | :--- | :--- |
|
|
| `GET` | `/ping/simple` | 🔓 Public | Erstellt einen Ping in der DB. Testet Schreibzugriff. |
|
|
| `GET` | `/ping/enhanced` | 🔓 Public | Testet Circuit Breaker. Parameter `simulate=true` löst Fehler aus. |
|
|
| `GET` | `/ping/health` | 🔓 Public | Gibt Status "UP" zurück. |
|
|
| `GET` | `/ping/public` | 🔓 Public | Expliziter Public-Test. |
|
|
| `GET` | `/ping/secure` | 🔒 **Secure** | Erfordert Token mit Rolle `MELD_USER`. Testet Auth-Flow. |
|
|
| `GET` | `/ping/sync` | 🔒 **Secure** | **Delta-Sync**. Liefert Änderungen seit `lastSyncTimestamp`. |
|
|
|
|
---
|
|
|
|
## 5. Getting Started
|
|
|
|
### A. Voraussetzungen
|
|
* Java 25 (oder kompatibel).
|
|
* Docker & Docker Compose (für Infrastruktur).
|
|
|
|
### B. Infrastruktur starten
|
|
Bevor der Service laufen kann, braucht er Datenbank und Keycloak.
|
|
```bash
|
|
# Im Root-Verzeichnis
|
|
docker compose --profile infra up -d
|
|
```
|
|
|
|
### C. Starten via Gradle (Lokal)
|
|
Ideal für Entwicklung und Debugging.
|
|
```bash
|
|
# Startet den Service im Profil "local"
|
|
./gradlew :backend:services:ping:ping-service:bootRun
|
|
```
|
|
* **URL:** `http://localhost:8082` (Direktzugriff)
|
|
* **Debug Port:** 5006
|
|
|
|
### D. Starten via Docker (Integration)
|
|
Testet den Service im Container-Verbund (hinter dem Gateway).
|
|
```bash
|
|
# Baut das Image und startet es zusammen mit dem Gateway
|
|
docker compose --profile backend up -d --build
|
|
```
|
|
* **URL (via Gateway):** `http://localhost:8081/api/ping/...`
|
|
|
|
---
|
|
|
|
## 6. Konfiguration
|
|
|
|
Die Konfiguration erfolgt primär über `application.yml` und Environment-Variables (12-Factor App).
|
|
|
|
| Variable | Default (Docker) | Beschreibung |
|
|
| :--- | :--- | :--- |
|
|
| `SERVER_PORT` | `8082` | Port des Services. |
|
|
| `POSTGRES_DB_URL` | `jdbc:postgresql://postgres:5432/...` | JDBC URL. |
|
|
| `SSEC_ISSUER_URI` | `http://keycloak:8080/...` | URL des Identity Providers (für Token-Check). |
|
|
| `CONSUL_HOST` | `consul` | Host für Service Discovery. |
|
|
|
|
### Profile
|
|
* `local`: Für lokale Entwicklung (nutzt `localhost` Adressen).
|
|
* `docker`: Für Betrieb im Docker-Netzwerk (nutzt Service-Namen wie `postgres`).
|
|
* `test`: Für Unit/Integration-Tests (nutzt H2 oder Testcontainers).
|
|
|
|
---
|
|
|
|
## 7. Testing
|
|
|
|
* **Unit Tests:** `./gradlew :backend:services:ping:ping-service:test`
|
|
* **Manuelle Tests:** Siehe [Testing with Postman](../Guides/Testing_with_Postman.md).
|