fixing(infra-messaging)
This commit is contained in:
+711
@@ -0,0 +1,711 @@
|
||||
# Meldestelle_Pro: Entwicklungs-Guideline
|
||||
|
||||
**Status:** Finalisiert & Verbindlich
|
||||
**Version:** 2.0
|
||||
**Stand:** August 2025
|
||||
|
||||
## 1. Vision & Architektonische Grundpfeiler
|
||||
|
||||
Dieses Dokument definiert die verbindlichen technischen Richtlinien und Qualitätsstandards für das Projekt "Meldestelle_Pro". Ziel ist die Schaffung einer modernen, skalierbaren und wartbaren Plattform für den Pferdesport.
|
||||
|
||||
Unsere Architektur basiert auf **vier Säulen**:
|
||||
|
||||
1. **Modularität & Skalierbarkeit** durch eine **Microservices-Architektur**
|
||||
2. **Fachlichkeit im Code** durch **Domain-Driven Design (DDD)**
|
||||
3. **Entkopplung & Resilienz** durch eine **ereignisgesteuerte Architektur (EDA)**
|
||||
4. **Effizienz & Konsistenz** durch eine **Multiplattform-Client-Strategie (KMP)**
|
||||
|
||||
> **Grundsatz:** Jede Code-Änderung muss diese vier Grundprinzipien respektieren.
|
||||
|
||||
---
|
||||
|
||||
## 2. Backend-Entwicklungsrichtlinien
|
||||
|
||||
#### 2.1. Microservice-Struktur (Clean Architecture)
|
||||
|
||||
**Jeder fachliche Microservice (z.B. :members, :events) muss der etablierten 4-Layer-Struktur folgen:**
|
||||
|
||||
* **`:*-api`**: Definiert die öffentliche Schnittstelle des Service (REST-Controller, DTOs).
|
||||
* **`:*-application`**: Enthält die Anwendungslogik und Use Cases. Hier werden die Repositories orchestriert.
|
||||
* **`:*-domain`**: Das Herz des Service. Enthält die reinen, von Frameworks unabhängigen Domänenmodelle, Geschäftsregeln
|
||||
und Repository-Interfaces.
|
||||
* **`:*-infrastructure`**: Die technische Implementierung der Interfaces aus der Domänenschicht (z.B. Datenbankzugriff
|
||||
mit Exposed).
|
||||
|
||||
#### 2.2. Domain-Driven Design (DDD) in der Praxis
|
||||
|
||||
* **Shared Kernel (`:core`-Modul):** Das `:core`-Modul ist heilig. Es darf **ausschließlich** fundamentalen,
|
||||
domänen-agnostischen Code enthalten. Fachspezifische Konzepte gehören in ihre jeweilige Domäne.
|
||||
* **Repository-Pattern mit `Result`:** Jede Repository-Methode muss das `Result`-Pattern verwenden, um Erfolgs- und
|
||||
Fehlerfälle explizit und typsicher zu behandeln.
|
||||
|
||||
```kotlin
|
||||
// Repository mit Result-Pattern
|
||||
interface MemberRepository {
|
||||
suspend fun findById(id: MemberId): Result<Member?, RepositoryError>
|
||||
suspend fun save(member: Member): Result<Unit, RepositoryError>
|
||||
suspend fun findByEmail(email: EmailAddress): Result<List<Member>, RepositoryError>
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.3. Core-Modul Spezifikation
|
||||
|
||||
Das `:core`-Modul definiert die fundamentalen Bausteine der gesamten Anwendung:
|
||||
|
||||
* **Result Extensions:** Utility-Funktionen für typsichere Fehlerbehandlung
|
||||
* **Common Types:** Basistypen für alle Domänen
|
||||
* **Shared Utilities:** Plattformunabhängige Hilfsfunktionen
|
||||
|
||||
```kotlin
|
||||
// Result Extensions im core-utils Modul
|
||||
inline fun <T, E, R> Result<T, E>.mapError(transform: (E) -> R): Result<T, R> =
|
||||
when (this) {
|
||||
is Result.Success -> Result.Success(value)
|
||||
is Result.Failure -> Result.Failure(transform(error))
|
||||
}
|
||||
|
||||
inline fun <T, E> Result<T, E>.onFailure(action: (E) -> Unit): Result<T, E> =
|
||||
also { if (it is Result.Failure) action(it.error) }
|
||||
|
||||
// Common Domain Types
|
||||
@JvmInline
|
||||
value class CorrelationId(val value: UUID) {
|
||||
companion object {
|
||||
fun generate(): CorrelationId = CorrelationId(UUID.randomUUID())
|
||||
fun of(value: String): Result<CorrelationId, ValidationError> =
|
||||
runCatching { UUID.fromString(value) }
|
||||
.map { CorrelationId(it) }
|
||||
.mapError { ValidationError.InvalidUUID("Invalid correlation ID: $value") }
|
||||
}
|
||||
}
|
||||
|
||||
// Konkrete Error-Implementierungen
|
||||
sealed class ValidationError(code: String, message: String) : DomainError(code, message) {
|
||||
data class InvalidUUID(override val message: String) :
|
||||
ValidationError("INVALID_UUID", message)
|
||||
data class InvalidEmail(override val message: String) :
|
||||
ValidationError("INVALID_EMAIL", message)
|
||||
data class InvalidLength(val field: String, val min: Int, val max: Int) :
|
||||
ValidationError("INVALID_LENGTH", "Field $field must be between $min and $max characters")
|
||||
}
|
||||
```
|
||||
|
||||
#### 2.4. Messaging & Event-Naming
|
||||
|
||||
* **Asynchrone Kommunikation:** Die bevorzugte Kommunikationsmethode ist asynchron über Kafka.
|
||||
* **Event-Naming Convention:** Domänen-Events folgen dem Muster `{Domain}{Entity}{Action}Event`.
|
||||
|
||||
```kotlin
|
||||
// Event-Naming Convention
|
||||
sealed class DomainEvent(
|
||||
val aggregateId: String,
|
||||
val version: Long,
|
||||
val timestamp: Instant = Instant.now()
|
||||
) {
|
||||
// Pattern: {Domain}{Entity}{Action}Event
|
||||
data class MemberPersonalDataUpdatedEvent(
|
||||
val memberId: MemberId,
|
||||
val personalData: PersonalData
|
||||
) : DomainEvent(memberId.value, version)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Frontend-Entwicklungsrichtlinien
|
||||
|
||||
#### 3.1. Architekturmuster: MVVM & KMP
|
||||
|
||||
Das Frontend folgt konsequent dem **Model-View-ViewModel (MVVM)**-Muster und der **Kotlin Multiplatform (KMP)**-Strategie:
|
||||
|
||||
* **Model & ViewModel:** Die gesamte Geschäftslogik, der Zustand und die API-Aufrufe leben im `:client:common-ui`-Modul und sind plattformunabhängig.
|
||||
* **View:** Die Benutzeroberfläche wird mit **Compose Multiplatform** im `:client:common-ui`-Modul implementiert.
|
||||
|
||||
#### 3.2. State Management
|
||||
|
||||
**Unidirectional Data Flow mit MVI-Pattern:**
|
||||
|
||||
```kotlin
|
||||
// State Management Pattern
|
||||
@Stable
|
||||
data class MemberListUiState(
|
||||
val members: List<Member> = emptyList(),
|
||||
val isLoading: Boolean = false,
|
||||
val error: String? = null,
|
||||
val searchQuery: String = ""
|
||||
)
|
||||
|
||||
sealed class MemberListIntent {
|
||||
object LoadMembers : MemberListIntent()
|
||||
data class SearchMembers(val query: String) : MemberListIntent()
|
||||
data class DeleteMember(val memberId: MemberId) : MemberListIntent()
|
||||
}
|
||||
|
||||
class MemberListViewModel(
|
||||
private val memberRepository: MemberRepository
|
||||
) : ViewModel() {
|
||||
private val _uiState = MutableStateFlow(MemberListUiState())
|
||||
val uiState: StateFlow<MemberListUiState> = _uiState.asStateFlow()
|
||||
|
||||
fun handleIntent(intent: MemberListIntent) {
|
||||
when (intent) {
|
||||
is MemberListIntent.LoadMembers -> loadMembers()
|
||||
is MemberListIntent.SearchMembers -> searchMembers(intent.query)
|
||||
is MemberListIntent.DeleteMember -> deleteMember(intent.memberId)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.3. Navigation Architecture
|
||||
|
||||
**Compose Navigation mit typsicheren Routes:**
|
||||
|
||||
```kotlin
|
||||
// Navigation Definition
|
||||
@Serializable
|
||||
sealed class Screen {
|
||||
@Serializable
|
||||
object MemberList : Screen()
|
||||
|
||||
@Serializable
|
||||
data class MemberDetail(val memberId: String) : Screen()
|
||||
|
||||
@Serializable
|
||||
data class EventRegistration(val eventId: String, val memberId: String) : Screen()
|
||||
}
|
||||
|
||||
// Navigation Router
|
||||
class NavigationRouter {
|
||||
private val _navigationEvents = MutableSharedFlow<NavigationEvent>()
|
||||
val navigationEvents: SharedFlow<NavigationEvent> = _navigationEvents.asSharedFlow()
|
||||
|
||||
fun navigateTo(screen: Screen) {
|
||||
_navigationEvents.tryEmit(NavigationEvent.NavigateTo(screen))
|
||||
}
|
||||
|
||||
fun navigateBack() {
|
||||
_navigationEvents.tryEmit(NavigationEvent.NavigateBack)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3.4. Vertikale Schnitte (Features)
|
||||
|
||||
Der UI-Code wird nach **fachlichen Features** strukturiert. Ein Feature (z.B. "Nennungsabwicklung") hat sein eigenes Verzeichnis und enthält alle zugehörigen Views, ViewModels und Models:
|
||||
|
||||
```
|
||||
client/common-ui/src/commonMain/kotlin/
|
||||
├── features/
|
||||
│ ├── members/
|
||||
│ │ ├── presentation/
|
||||
│ │ │ ├── MemberListViewModel.kt
|
||||
│ │ │ ├── MemberDetailViewModel.kt
|
||||
│ │ │ └── MemberUiState.kt
|
||||
│ │ ├── ui/
|
||||
│ │ │ ├── MemberListScreen.kt
|
||||
│ │ │ ├── MemberDetailScreen.kt
|
||||
│ │ │ └── components/
|
||||
│ │ └── domain/
|
||||
│ │ └── MemberUseCases.kt
|
||||
│ └── events/
|
||||
│ ├── presentation/
|
||||
│ ├── ui/
|
||||
│ └── domain/
|
||||
```
|
||||
|
||||
#### 3.5. Platform-spezifische Implementierungen
|
||||
|
||||
**Desktop-spezifische Features:**
|
||||
|
||||
```kotlin
|
||||
// Desktop-specific implementations
|
||||
actual class PlatformFileManager {
|
||||
actual suspend fun selectFile(): Result<File?, FileError> {
|
||||
return withContext(Dispatchers.IO) {
|
||||
try {
|
||||
val fileChooser = JFileChooser()
|
||||
val result = fileChooser.showOpenDialog(null)
|
||||
if (result == JFileChooser.APPROVE_OPTION) {
|
||||
Result.Success(fileChooser.selectedFile)
|
||||
} else {
|
||||
Result.Success(null)
|
||||
}
|
||||
} catch (e: Exception) {
|
||||
Result.Failure(FileError.SelectionFailed(e.message))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Web-specific implementations
|
||||
actual class PlatformFileManager {
|
||||
actual suspend fun selectFile(): Result<File?, FileError> {
|
||||
return try {
|
||||
val input = document.createElement("input") as HTMLInputElement
|
||||
input.type = "file"
|
||||
input.click()
|
||||
// Implementation für Web File API
|
||||
Result.Success(null) // Simplified
|
||||
} catch (e: Exception) {
|
||||
Result.Failure(FileError.SelectionFailed(e.message))
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. API-Versioning & Kompatibilität
|
||||
|
||||
#### 4.1. Versioning-Strategie
|
||||
|
||||
**Header-basierte Versionierung (Empfohlen):**
|
||||
|
||||
```kotlin
|
||||
// API Version Header
|
||||
@RestController
|
||||
@RequestMapping("/api/members")
|
||||
class MemberController {
|
||||
|
||||
@GetMapping
|
||||
fun getMembers(
|
||||
@RequestHeader(value = "API-Version", defaultValue = "1.0") version: String,
|
||||
@RequestParam query: String?
|
||||
): ResponseEntity<List<MemberDto>> {
|
||||
return when (version) {
|
||||
"1.0" -> memberService.getMembersV1(query)
|
||||
"2.0" -> memberService.getMembersV2(query)
|
||||
else -> ResponseEntity.status(HttpStatus.NOT_ACCEPTABLE).build()
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Client-seitige Versionierung
|
||||
class ApiClient {
|
||||
companion object {
|
||||
const val CURRENT_API_VERSION = "2.0"
|
||||
const val MIN_SUPPORTED_VERSION = "1.0"
|
||||
}
|
||||
|
||||
private val defaultHeaders = mapOf(
|
||||
"API-Version" to CURRENT_API_VERSION,
|
||||
"Accept" to "application/json"
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.2. Backward Compatibility Rules
|
||||
|
||||
* **Breaking Changes:** Erfordern eine neue Major-Version (1.x → 2.x)
|
||||
* **Additive Changes:** Können in Minor-Versionen erfolgen (1.0 → 1.1)
|
||||
* **Bug Fixes:** Patch-Versionen (1.0.0 → 1.0.1)
|
||||
|
||||
```kotlin
|
||||
// Compatibility Matrix
|
||||
object ApiCompatibility {
|
||||
val supportedVersions = mapOf(
|
||||
"2.0" to ApiVersionConfig(
|
||||
deprecated = false,
|
||||
sunsetDate = null,
|
||||
features = setOf("advanced-search", "bulk-operations")
|
||||
),
|
||||
"1.0" to ApiVersionConfig(
|
||||
deprecated = true,
|
||||
sunsetDate = LocalDate.of(2025, 12, 31),
|
||||
features = setOf("basic-search")
|
||||
)
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.3. Versioning Lifecycle Management
|
||||
|
||||
* **Deprecation Notice:** Mindestens 6 Monate vor Entfernung
|
||||
* **Documentation:** Alle Versionen müssen in OpenAPI dokumentiert sein
|
||||
* **Migration Guide:** Für jede Major-Version erforderlich
|
||||
|
||||
---
|
||||
|
||||
## 5. Allgemeine Qualitätsstandards
|
||||
|
||||
#### 4.1. Code-Qualität & Kotlin-Konventionen
|
||||
|
||||
* **Value Classes für Typsicherheit:** Primitive Typen (UUID, String, Long) für IDs oder spezifische Werte müssen in
|
||||
typsichere `value class`-Wrapper gekapselt werden, um Fehler zu vermeiden.
|
||||
|
||||
```kotlin
|
||||
// Ergänzung für Value Objects
|
||||
@JvmInline
|
||||
value class MemberId(val value: UUID) {
|
||||
companion object {
|
||||
fun of(value: String): Result<MemberId, ValidationError> =
|
||||
runCatching { UUID.fromString(value) }
|
||||
.map { MemberId(it) }
|
||||
.mapError { ValidationError.INVALID_UUID }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.2. Error-Handling
|
||||
|
||||
* **`Result`-Pattern statt Exceptions:** Für erwartbare Geschäftsfehler ist das `Result`-Pattern zu verwenden.
|
||||
* **Spezifische Fehler-Hierarchie:** Wir verwenden eine `sealed class`-Hierarchie, um Fehlerarten klar zu
|
||||
kategorisieren.
|
||||
|
||||
```kotlin
|
||||
// Spezifische Error-Hierarchie definieren
|
||||
sealed class DomainError(val code: String, val message: String)
|
||||
sealed class ValidationError(code: String, message: String) : DomainError(code, message)
|
||||
sealed class BusinessError(code: String, message: String) : DomainError(code, message)
|
||||
sealed class TechnicalError(code: String, message: String) : DomainError(code, message)
|
||||
```
|
||||
|
||||
#### 4.3. Testing
|
||||
|
||||
* **Testcontainers als Goldstandard:** Jede Interaktion mit externer Infrastruktur (DB, Cache, Broker) **muss** mit *
|
||||
*Testcontainers** getestet werden.
|
||||
* **Mocking für Isolation:** Abhängigkeiten innerhalb von Tests werden mit Mocking-Frameworks (z.B. MockK) isoliert, um
|
||||
den Testfokus zu schärfen.
|
||||
|
||||
```kotlin
|
||||
// Testcontainers-Pattern für Infrastruktur-Tests
|
||||
@TestConfiguration
|
||||
class KafkaTestConfig {
|
||||
@Bean
|
||||
@Primary
|
||||
fun kafkaEventPublisher(): KafkaEventPublisher = mockk()
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. Infrastruktur-Spezifikationen
|
||||
|
||||
#### 5.1. Kafka-Konfiguration
|
||||
|
||||
Die Konfiguration für Producer und Consumer muss produktionsreife Einstellungen für Zuverlässigkeit und Datenkonsistenz
|
||||
verwenden.
|
||||
|
||||
```YAML
|
||||
# Ergänzung für application.yml
|
||||
kafka:
|
||||
producer:
|
||||
acks: all
|
||||
enable-idempotence: true
|
||||
max-in-flight-requests-per-connection: 1
|
||||
consumer:
|
||||
group-id-prefix: "meldestelle-${spring.application.name}"
|
||||
auto-offset-reset: earliest
|
||||
enable-auto-commit: false
|
||||
```
|
||||
|
||||
#### 5.2. Datenbank-Migrationen mit Flyway
|
||||
|
||||
Migrations-Skripte müssen einer klaren Namenskonvention folgen.
|
||||
|
||||
* **Pattern:**`V{version}__{description}.sql` (z.B., `V001__Create_member_tables.sql`)
|
||||
|
||||
* **Repeatable:**`R__{description}.sql` (z.B., `R__Update_member_view.sql`)
|
||||
|
||||
---
|
||||
|
||||
## 6. Monitoring & Observability
|
||||
|
||||
#### 6.1. Structured Logging
|
||||
|
||||
Logs müssen als strukturierte Daten (z.B. JSON) ausgegeben werden und immer eine Korrelations-ID enthalten, um Anfragen über Service-Grenzen hinweg verfolgen zu können.
|
||||
|
||||
```kotlin
|
||||
// Korrigierte Logging-Syntax
|
||||
@Component
|
||||
class MemberService {
|
||||
private val logger = KotlinLogging.logger {}
|
||||
|
||||
suspend fun createMember(command: CreateMemberCommand) {
|
||||
logger.info {
|
||||
mapOf(
|
||||
"message" to "Creating member",
|
||||
"memberId" to command.memberId.value,
|
||||
"operation" to "create_member",
|
||||
"correlationId" to MDC.get("correlationId")
|
||||
).toString()
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 6.2. Service Level Indicators (SLIs) & Objectives (SLOs)
|
||||
|
||||
**Definierte SLIs für alle Services:**
|
||||
|
||||
```kotlin
|
||||
// SLI/SLO Definitionen
|
||||
object ServiceLevelIndicators {
|
||||
|
||||
// Availability SLIs
|
||||
data class AvailabilitySLI(
|
||||
val serviceName: String,
|
||||
val targetUptime: Double = 0.995, // 99.5%
|
||||
val measurementWindow: Duration = Duration.ofDays(30)
|
||||
)
|
||||
|
||||
// Latency SLIs
|
||||
data class LatencySLI(
|
||||
val serviceName: String,
|
||||
val percentile: Double = 0.95, // P95
|
||||
val targetLatency: Duration = Duration.ofMillis(500),
|
||||
val measurementWindow: Duration = Duration.ofMinutes(5)
|
||||
)
|
||||
|
||||
// Error Rate SLIs
|
||||
data class ErrorRateSLI(
|
||||
val serviceName: String,
|
||||
val maxErrorRate: Double = 0.001, // 0.1%
|
||||
val measurementWindow: Duration = Duration.ofMinutes(5)
|
||||
)
|
||||
}
|
||||
|
||||
// SLO Monitoring
|
||||
@Component
|
||||
class SLOMonitor(private val meterRegistry: MeterRegistry) {
|
||||
|
||||
private val requestDuration = Timer.builder("http.request.duration")
|
||||
.description("HTTP request duration")
|
||||
.register(meterRegistry)
|
||||
|
||||
private val errorRate = Counter.builder("http.request.errors")
|
||||
.description("HTTP request errors")
|
||||
.register(meterRegistry)
|
||||
|
||||
fun recordRequest(duration: Duration, isError: Boolean) {
|
||||
requestDuration.record(duration)
|
||||
if (isError) errorRate.increment()
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 6.3. Business & Technical Metrics
|
||||
|
||||
**Umfassende Metriken-Strategie:**
|
||||
|
||||
```kotlin
|
||||
// Business Metrics
|
||||
@Component
|
||||
class BusinessMetrics(meterRegistry: MeterRegistry) {
|
||||
|
||||
// Fachliche Metriken
|
||||
private val memberRegistrations = Counter.builder("business.member.registrations.total")
|
||||
.description("Total number of member registrations")
|
||||
.tag("service", "members")
|
||||
.register(meterRegistry)
|
||||
|
||||
private val eventParticipations = Counter.builder("business.event.participations.total")
|
||||
.description("Total event participations")
|
||||
.tag("service", "events")
|
||||
.register(meterRegistry)
|
||||
|
||||
private val paymentTransactions = Timer.builder("business.payment.transaction.duration")
|
||||
.description("Payment transaction processing time")
|
||||
.tag("service", "payments")
|
||||
.register(meterRegistry)
|
||||
|
||||
// Gauge für aktuelle Werte
|
||||
private val activeSessions = Gauge.builder("business.active.sessions")
|
||||
.description("Currently active user sessions")
|
||||
.register(meterRegistry) { getActiveSessionCount() }
|
||||
}
|
||||
|
||||
// Technical Metrics
|
||||
@Component
|
||||
class TechnicalMetrics(meterRegistry: MeterRegistry) {
|
||||
|
||||
// Database Metriken
|
||||
private val dbConnectionPool = Gauge.builder("database.connection.pool.active")
|
||||
.description("Active database connections")
|
||||
.register(meterRegistry) { getActiveConnections() }
|
||||
|
||||
// Kafka Metriken
|
||||
private val kafkaLag = Gauge.builder("kafka.consumer.lag")
|
||||
.description("Kafka consumer lag")
|
||||
.register(meterRegistry) { getConsumerLag() }
|
||||
|
||||
// Cache Metriken
|
||||
private val cacheHitRate = Gauge.builder("cache.hit.rate")
|
||||
.description("Cache hit rate percentage")
|
||||
.register(meterRegistry) { getCacheHitRate() }
|
||||
}
|
||||
```
|
||||
|
||||
#### 6.4. Alerting Strategy
|
||||
|
||||
**Alert-Definitionen basierend auf SLOs:**
|
||||
|
||||
```yaml
|
||||
# Prometheus Alert Rules
|
||||
groups:
|
||||
- name: slo.rules
|
||||
rules:
|
||||
- alert: HighErrorRate
|
||||
expr: rate(http_request_errors_total[5m]) > 0.001
|
||||
for: 2m
|
||||
labels:
|
||||
severity: warning
|
||||
annotations:
|
||||
summary: "High error rate detected"
|
||||
|
||||
- alert: HighLatency
|
||||
expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 0.5
|
||||
for: 5m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "High latency detected"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Zusätzliche Richtlinien
|
||||
|
||||
#### 7.1. Security
|
||||
|
||||
Die Autorisierung muss auf Methodenebene mit Spring Security Annotations (`@PreAuthorize`) durchgesetzt werden, um eine feingranulare Zugriffskontrolle zu gewährleisten.
|
||||
|
||||
**JWT Implementation:**
|
||||
|
||||
```kotlin
|
||||
// JWT Configuration
|
||||
@Configuration
|
||||
@EnableWebSecurity
|
||||
class SecurityConfig {
|
||||
|
||||
@Bean
|
||||
fun jwtAuthenticationFilter(): JwtAuthenticationFilter {
|
||||
return JwtAuthenticationFilter()
|
||||
}
|
||||
|
||||
@Bean
|
||||
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
|
||||
return http
|
||||
.csrf { it.disable() }
|
||||
.sessionManagement { it.sessionCreationPolicy(SessionCreationPolicy.STATELESS) }
|
||||
.authorizeHttpRequests { auth ->
|
||||
auth.requestMatchers("/api/auth/**").permitAll()
|
||||
.requestMatchers(HttpMethod.GET, "/api/members/**").hasRole("USER")
|
||||
.requestMatchers(HttpMethod.POST, "/api/members/**").hasRole("ADMIN")
|
||||
.anyRequest().authenticated()
|
||||
}
|
||||
.addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter::class.java)
|
||||
.build()
|
||||
}
|
||||
}
|
||||
|
||||
// Method-level Security
|
||||
@RestController
|
||||
@RequestMapping("/api/members")
|
||||
class MemberController {
|
||||
|
||||
@GetMapping("/{id}")
|
||||
@PreAuthorize("hasRole('USER') or @memberService.isOwner(#id, authentication.name)")
|
||||
fun getMember(@PathVariable id: String): MemberDto {
|
||||
// Implementation
|
||||
}
|
||||
|
||||
@PostMapping
|
||||
@PreAuthorize("hasRole('ADMIN') or hasPermission(#memberDto, 'CREATE')")
|
||||
fun createMember(@RequestBody memberDto: MemberDto): MemberDto {
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**OAuth2 Integration:**
|
||||
|
||||
```kotlin
|
||||
// OAuth2 Resource Server Configuration
|
||||
@Configuration
|
||||
class OAuth2Config {
|
||||
|
||||
@Bean
|
||||
fun jwtDecoder(): JwtDecoder {
|
||||
return NimbusJwtDecoder.withJwkSetUri("https://auth-provider/.well-known/jwks.json").build()
|
||||
}
|
||||
|
||||
@Bean
|
||||
fun jwtAuthenticationConverter(): JwtAuthenticationConverter {
|
||||
val converter = JwtAuthenticationConverter()
|
||||
converter.setJwtGrantedAuthoritiesConverter { jwt ->
|
||||
val authorities = jwt.getClaimAsStringList("authorities") ?: emptyList()
|
||||
authorities.map { SimpleGrantedAuthority("ROLE_$it") }
|
||||
}
|
||||
return converter
|
||||
}
|
||||
}
|
||||
|
||||
// Custom Permission Evaluator
|
||||
@Component("memberService")
|
||||
class MemberPermissionEvaluator {
|
||||
|
||||
fun isOwner(memberId: String, username: String): Boolean {
|
||||
return memberRepository.findById(memberId)
|
||||
?.let { it.email == username }
|
||||
?: false
|
||||
}
|
||||
|
||||
fun hasPermission(target: Any, permission: String): Boolean {
|
||||
// Custom permission logic
|
||||
return when (permission) {
|
||||
"CREATE" -> hasCreatePermission(target)
|
||||
"UPDATE" -> hasUpdatePermission(target)
|
||||
else -> false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Rate Limiting:**
|
||||
|
||||
```kotlin
|
||||
// Rate Limiting Configuration
|
||||
@Configuration
|
||||
class RateLimitConfig {
|
||||
|
||||
@Bean
|
||||
fun rateLimitFilter(): RateLimitFilter {
|
||||
return RateLimitFilter(
|
||||
rateLimiters = mapOf(
|
||||
"/api/auth/login" to RateLimiter.create(5.0), // 5 requests per second
|
||||
"/api/members" to RateLimiter.create(100.0), // 100 requests per second
|
||||
"/api/events" to RateLimiter.create(50.0) // 50 requests per second
|
||||
)
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
// Custom Rate Limit Annotation
|
||||
@Target(AnnotationTarget.FUNCTION)
|
||||
@Retention(AnnotationRetention.RUNTIME)
|
||||
annotation class RateLimit(
|
||||
val requestsPerSecond: Double = 10.0,
|
||||
val burstCapacity: Int = 20
|
||||
)
|
||||
|
||||
// Usage
|
||||
@RestController
|
||||
class AuthController {
|
||||
|
||||
@PostMapping("/login")
|
||||
@RateLimit(requestsPerSecond = 5.0, burstCapacity = 10)
|
||||
fun login(@RequestBody loginRequest: LoginRequest): AuthResponse {
|
||||
// Implementation
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 7.2. Performance
|
||||
|
||||
Cache-Strategien (`@Cacheable`, `@CacheEvict`) **müssen gezielt eingesetzt werden**, um die Latenz bei häufigen Lesezugriffen zu minimieren.
|
||||
|
||||
#### 7.3. Dokumentation
|
||||
|
||||
Alle öffentlichen REST-Endpunkte müssen mit OpenAPI-Annotationen (`@Operation`, `@ApiResponse`) dokumentiert werden, um eine klare und interaktive API-Dokumentation zu generieren.
|
||||
Reference in New Issue
Block a user