chore(docs, platform): finalize migration guides for Exposed 1.0.0 and Ktor 3.4.0 upgrades
- Updated Exposed migration guide with detailed breaking changes, migration steps, test matrix, and rollback plan. - Published technical analysis for transitioning to Ktor 3.4.0, including API improvements and routing OpenAPI integration. - Aligned `platform-bom` with upgraded dependencies: `exposed` 1.0.0 and `ktor` 3.4.0. - Introduced `ktor-server-routing-openapi` dependency for dynamic API documentation support.
This commit is contained in:
parent
3d940ae4b1
commit
9e5e0512ce
|
|
@ -1,12 +1,20 @@
|
|||
Hier ist eine Zusammenfassung der spezifischen Breaking Changes beim Upgrade von **Exposed 1.0.0-rc-4 auf die stabile
|
||||
Version 1.0.0** im Markdown-Format:
|
||||
---
|
||||
type: Reference
|
||||
status: ACTIVE
|
||||
owner: Lead Architect
|
||||
date: 2026-01-31
|
||||
---
|
||||
|
||||
# Breaking Changes: JetBrains Exposed 1.0.0-rc-4 -> 1.0.0
|
||||
# Architektonische Evolution – Migrationsleitfaden: Exposed 1.0.0-rc-4 → 1.0.0
|
||||
|
||||
Dieses Dokument fasst die technischen Änderungen zusammen, die beim Übergang vom letzten Release Candidate (rc-4) zur
|
||||
stabilen Version 1.0.0 zu beachten sind.
|
||||
Dieses Dokument fasst die Auswirkungen und konkreten Migrationsschritte für das Update von JetBrains Exposed
|
||||
von `1.0.0-rc-4` auf die stabile Version `1.0.0` zusammen. Ziel ist eine sichere, reproduzierbare Migration ohne
|
||||
Regressionsrisiken und unter Wahrung unserer Architektur-Governance (API/Domain/Infrastructure-Trennung, zentrale
|
||||
Versionierung über Platform/BOM).
|
||||
|
||||
## 1. Überarbeitung der UUID-Unterstützung (Kotlin Multiplatform)
|
||||
## 1. Breaking Changes (relevant für uns)
|
||||
|
||||
### 1.1 Überarbeitung der UUID-Unterstützung (Kotlin Multiplatform)
|
||||
|
||||
Aufgrund der Einführung der nativen `kotlin.uuid.Uuid` mussten bestehende Klassen, die auf `java.util.UUID` basieren,
|
||||
verschoben werden, um Namenskollisionen zu vermeiden.
|
||||
|
|
@ -25,7 +33,7 @@ verschoben werden, um Namenskollisionen zu vermeiden.
|
|||
* **Migrationspfad:** Für die Weiterverwendung von `java.util.UUID` muss stattdessen die neue Extension-Funktion
|
||||
`Table.javaUUID()` genutzt werden.
|
||||
|
||||
## 2. Refactoring des Transaction Managers
|
||||
### 1.2 Refactoring des Transaction Managers
|
||||
|
||||
Die Typisierung der Transaction Manager wurde spezifiziert, um besser zwischen JDBC und R2DBC zu unterscheiden.
|
||||
|
||||
|
|
@ -38,7 +46,7 @@ Die Typisierung der Transaction Manager wurde spezifiziert, um besser zwischen J
|
|||
* **Ersatz:** Nutzen Sie stattdessen die Extension-Funktionen `JdbcTransactionManager.currentOrNull()` /
|
||||
`R2dbcTransactionManager.currentOrNull()` oder die statische Methode `TransactionManager.currentOrNull()`.
|
||||
|
||||
## 3. R2DBC API Bereinigungen
|
||||
### 1.3 R2DBC API Bereinigungen
|
||||
|
||||
Um die API näher an die zugrunde liegenden Treiber-Spezifikationen (io.r2dbc.spi) zu bringen, wurden ungenutzte Methoden
|
||||
entfernt.
|
||||
|
|
@ -49,7 +57,7 @@ entfernt.
|
|||
* **Methoden-Umbenennung:** `R2dbcTransaction.closeExecutedStatements()` wurde in `.clearExecutedStatements()`
|
||||
umbenannt. Diese Methode ist nun nicht mehr suspendierbar (`non-suspending`).
|
||||
|
||||
## 4. SQLite & JSONB Automatisierung
|
||||
### 1.4 SQLite & JSONB Automatisierung
|
||||
|
||||
Das Handling von JSONB-Spalten in SQLite wurde vereinheitlicht.
|
||||
|
||||
|
|
@ -61,10 +69,51 @@ Das Handling von JSONB-Spalten in SQLite wurde vereinheitlicht.
|
|||
* **Core-Interface:** Das Interface `JsonColumnMarker` in `exposed-core` wurde um die Eigenschaft
|
||||
`needsBinaryFormatCast` erweitert.
|
||||
|
||||
## 5. Sonstige Anpassungen
|
||||
### 1.5 Sonstige Anpassungen
|
||||
|
||||
* **Logging-Level:** Die Protokollierung für Transaction-Retry-Verzögerungen und Rollback-Fehler wurde von `WARN` auf
|
||||
`DEBUG` herabgestuft.
|
||||
|
||||
* **Transaktions-ID:** Das Feld `Transaction.id` wurde endgültig in `Transaction.transactionId` umbenannt, um
|
||||
Shadowing-Probleme mit Benutzer-Code zu vermeiden.
|
||||
|
||||
---
|
||||
|
||||
## 2. Migrationsschritte (How-To)
|
||||
|
||||
1. Zentralversion heben:
|
||||
- `gradle/libs.versions.toml`: `exposed = "1.0.0"` setzen.
|
||||
- Platform-BOM importieren; keine Direktversionen in Modul-Builds.
|
||||
2. UUID-Pfade prüfen:
|
||||
- Nutzung von `Table.uuid()` evaluieren; falls `java.util.UUID` benötigt, auf `Table.javaUUID()` wechseln.
|
||||
- Etwaige Referenzen auf verschobene `.UUID*`-Typen auf das neue `.java`-Subpaket anpassen.
|
||||
3. TransactionManager-Aufrufe:
|
||||
- Verwendungen von `TransactionManagerApi.currentOrNull()` entfernen.
|
||||
- Stattdessen `JdbcTransactionManager.currentOrNull()` bzw. `TransactionManager.currentOrNull()` einsetzen.
|
||||
4. R2DBC (falls verwendet):
|
||||
- Entfernte Methoden (`closeIfPossible`, `cancel`) nicht mehr aufrufen.
|
||||
- Umbenennung auf `.clearExecutedStatements()` berücksichtigen (non-suspending).
|
||||
5. JSON/SQLite:
|
||||
- Verhalten von `jsonb()` mit `castToJsonFormat` prüfen und ggf. deaktivieren.
|
||||
|
||||
## 3. Test-Matrix
|
||||
|
||||
- Unit: DSL-Typen (UUID, Zeittypen), Mappings, einfache Inserts/Selects.
|
||||
- Integration: JDBC/Hikari Konfiguration, `batchInsert`, Upsert/Ignore-Pfade.
|
||||
- E2E (Docker): CRUD-Flows über den Service hinweg; Metriken/Health.
|
||||
|
||||
## 4. Rollback-Plan
|
||||
|
||||
- `git revert` des Version-Bumps in `libs.versions.toml` und ggf. betroffener Anpassungs-Commits.
|
||||
- Rebuild; E2E-Smoketest durchführen.
|
||||
- Dokumentenstatus auf `ARCHIVED` setzen oder Nachtrag mit „Rollback erfolgt“ ergänzen.
|
||||
|
||||
## 5. Diagramm (Flow)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Version Catalog: exposed=1.0.0] --> B[Platform BOM constraints]
|
||||
B --> C[Module Build]
|
||||
C --> D[Unit/Integration Tests]
|
||||
D --> E[Docker E2E]
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,3 +1,10 @@
|
|||
---
|
||||
type: Reference
|
||||
status: ACTIVE
|
||||
owner: Lead Architect
|
||||
date: 2026-01-31
|
||||
---
|
||||
|
||||
# Technische Analyse: Ktor Framework Migration (3.3.3 -> 3.4.0)
|
||||
|
||||
### Einleitung und Management-Zusammenfassung
|
||||
|
|
@ -76,7 +83,12 @@ statt statische Dateien beim Build zu erzeugen.
|
|||
- **Neues Feature:** Du kannst Routen nun direkt im Code beschreiben
|
||||
|
||||
```kotlin
|
||||
get("/users") { ... }.describe { summary = "Getusers" response < List >(HttpStatusCode.OK) }
|
||||
get("/users") {
|
||||
// ...
|
||||
}.describe {
|
||||
summary = "Get users"
|
||||
response<List<User>>(HttpStatusCode.OK)
|
||||
}
|
||||
```
|
||||
|
||||
Dadurch sind Code und Dokumentation immer synchron.
|
||||
|
|
|
|||
|
|
@ -23,8 +23,8 @@ androidx-lifecycle = "2.9.6"
|
|||
uiDesktop = "1.7.0"
|
||||
|
||||
# Network: Ktor (Client & Server)
|
||||
# Kotlin 2.3.0 Alignment + iOS SSE Fix
|
||||
ktor = "3.3.3"
|
||||
# Align with Kotlin 2.3.0 – upgrade to 3.4.0 (runtime OpenAPI + lifecycle improvements)
|
||||
ktor = "3.4.0"
|
||||
|
||||
# Dependency Injection
|
||||
koin = "4.1.1"
|
||||
|
|
@ -46,7 +46,8 @@ springDependencyManagement = "1.1.7"
|
|||
springdoc = "3.0.0"
|
||||
|
||||
# Server Persistence
|
||||
exposed = "1.0.0-rc-4"
|
||||
# Final release 1.0.0 (UUID API refinements vs rc-4)
|
||||
exposed = "1.0.0"
|
||||
postgresql = "42.7.8"
|
||||
hikari = "7.0.2"
|
||||
h2 = "2.4.240"
|
||||
|
|
@ -208,6 +209,7 @@ ktor-server-openapi = { module = "io.ktor:ktor-server-openapi", version.ref = "k
|
|||
ktor-server-swagger = { module = "io.ktor:ktor-server-swagger", version.ref = "ktor" }
|
||||
ktor-server-tests = { module = "io.ktor:ktor-server-tests-jvm", version.ref = "ktor" }
|
||||
ktor-server-testHost = { module = "io.ktor:ktor-server-test-host-jvm", version.ref = "ktor" }
|
||||
ktor-server-routing-openapi = { module = "io.ktor:ktor-server-routing-openapi", version.ref = "ktor" }
|
||||
|
||||
# ==============================================================================
|
||||
# === BACKEND: PERSISTENCE & INFRA ===
|
||||
|
|
|
|||
|
|
@ -63,6 +63,8 @@ dependencies {
|
|||
// --- Jackson Modules ---
|
||||
api(libs.jackson.module.kotlin)
|
||||
api(libs.jackson.datatype.jsr310)
|
||||
// --- Ktor OpenAPI (runtime-based docs require explicit routing-openapi in 3.4.0) ---
|
||||
api("io.ktor:ktor-server-routing-openapi:${libs.versions.ktor.get()}")
|
||||
// --- Testcontainers ---
|
||||
// Testcontainers Bundle kann nicht direkt in constraints verwendet werden
|
||||
api(libs.testcontainers.core)
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user