Fachlicher Vertrag: unverändert zu erhalten
- Collection-Name, _id und Dokumentfeldnamen bleiben kompatibel.
- Fehlende/zusätzliche Felder werden versionstolerant behandelt.
- Indexannahmen werden explizit geprüft.
MongoDB Document und manueller Mapper wird nachvollziehbar in Spring Data MongoDB Document/Repository überführt. Die Akte zeigt nicht nur das Ziel, sondern die tatsächlichen Dateien, APIs, Dependencies, Codebelege, Tests, Risiken und Cutover-Schritte.
| Dimension | Legacy | Modern | Migrationskonsequenz |
|---|---|---|---|
| Programmiermodell | imperativ / ohne Framework-Annotationen | Document, Id | Annotationen und Containerfunktionen werden nur dort eingesetzt, wo sie eine konkrete technische Verantwortung übernehmen. |
| Abhängigkeiten | 2 direkte Dependencies | 2 direkte Dependencies | 2 neu, 2 entfernt; Versionen und transitive Auswirkungen im erfolgreichen Online-Build prüfen. |
| Öffentliche API | 4 erkannte Methoden | 0 erkannte Methoden | Methoden werden nach fachlicher Rolle gemappt; reine Bootstrap- und Framework-Methoden sind kein fachlicher Vertrag. |
| Datenmodell | class LegacyBookMapper, class LegacyBookRepository, record LegacyBook | interface BookRepository, record BookDocument | Feldnamen, IDs, Null-Semantik, Gleichheit und Serialisierungsform werden separat regressionstestet. |
| Fehlerverhalten | Legacy-Exceptions und Rückgabewerte | explizitere Fach-/Framework-Fehlerabbildung | Fehler dürfen nicht nur technisch übersetzt werden; Status, Ursache, Retrybarkeit und Client-Vertrag müssen erhalten oder versioniert werden. |
| Tests | Bestands- und Golden-Master-Tests | Unit-, Slice-, Contract- und Integrationstests | Der Modern-Pfad wird zuerst gegen denselben fachlichen Vektor geprüft und danach um neue technische Risiken ergänzt. |
| Betrieb | Legacy-Start/Lifecycle | modernes Packaging, Health und externe Konfiguration | Migration mit produktionsnahen Daten, Backups, Restore-Probe und Query-/Lock-Monitoring absichern. |
| Rollback | Legacy-Artefakt bleibt unverändert | Modern-Artefakt getrennt deploybar | Kein Rollback über Datenverlust: Schema, Nachrichten und verschlüsselte Daten müssen rückwärtslesbar oder durch Dual-Read abgesichert sein. |
document shape and mapping compatibility
mapping, missing fields, query and index assumptions
Die Zuordnung ist semantisch: Eine Legacy-Klasse kann in mehrere moderne Rollen zerlegt werden.
| Legacy-Rolle / Datei | Modern-Rolle / Datei | Bedeutung |
|---|---|---|
| LegacyBook.java | BookDocument.java | BSON-Datenform wird annotiertes Spring-Data-Dokument. |
| LegacyBookMapper.java + LegacyBookRepository.java | BookRepository.java | Manueller Mapper/Driver wird Repository-Abstraktion. |
| Datei | Typ | Annotationen | öffentliche API | Pattern | Zeilen |
|---|---|---|---|---|---|
| LegacyBook.java | record LegacyBook | — | — | — | 4 |
| LegacyBookMapper.java | class LegacyBookMapper | — | Document toDocument(LegacyBook b) LegacyBook fromDocument(Document d) | Data Mapper | 15 |
| LegacyBookRepository.java | class LegacyBookRepository | — | void save(LegacyBook book) List<LegacyBook> findByYearGreaterThanEqual(int year) | Repository | 31 |
| Datei | Typ | Annotationen | öffentliche API | Pattern | Zeilen |
|---|---|---|---|---|---|
| BookDocument.java | record BookDocument | Document, Id | — | — | 8 |
| BookRepository.java | interface BookRepository | — | — | Repository | 10 |
| Status | Dependency | Version | Scope | Prüfung |
|---|---|---|---|---|
| ENTFERNT | org.junit.jupiter:junit-jupiter | BOM/Parent | test | Legacy-Laufzeit entfällt oder wird durch Plattform/BOM ersetzt. |
| ENTFERNT | org.mongodb:mongodb-driver-sync | BOM/Parent | compile | Legacy-Laufzeit entfällt oder wird durch Plattform/BOM ersetzt. |
| NEU | org.springframework.boot:spring-boot-starter-data-mongodb | BOM/Parent | compile | Neue Laufzeit-/Testabhängigkeit; transitiv, lizenz- und security-seitig prüfen. |
| NEU | org.springframework.boot:spring-boot-starter-test | BOM/Parent | test | Neue Laufzeit-/Testabhängigkeit; transitiv, lizenz- und security-seitig prüfen. |
Die folgenden Ausschnitte stammen direkt aus den enthaltenen Projekten. Dadurch ist sichtbar, welche Verantwortung tatsächlich verschoben wurde.
Migrationsbedeutung: BSON-Datenform wird annotiertes Spring-Data-Dokument.
projects/24-mongodb/legacy/src/main/java/at/aydin/lab/mongodb/legacy/LegacyBook.java
package at.aydin.lab.mongodb.legacy;
public record LegacyBook(String id, String title, int year) {
}
projects/24-mongodb/modern/src/main/java/at/aydin/lab/mongodb/modern/BookDocument.java
package at.aydin.lab.mongodb.modern;
import org.springframework.data.annotation.Id;
import org.springframework.data.mongodb.core.mapping.Document;
@Document("books")
public record BookDocument(@Id String id, String title, int year) {
}
--- LegacyBook.java
+++ BookDocument.java
@@ -1,4 +1,8 @@
-package at.aydin.lab.mongodb.legacy;
+package at.aydin.lab.mongodb.modern;
-public record LegacyBook(String id, String title, int year) {
+import org.springframework.data.annotation.Id;
+import org.springframework.data.mongodb.core.mapping.Document;
+
+@Document("books")
+public record BookDocument(@Id String id, String title, int year) {
}
Migrationsbedeutung: Manueller Mapper/Driver wird Repository-Abstraktion.
projects/24-mongodb/legacy/src/main/java/at/aydin/lab/mongodb/legacy/LegacyBookMapper.java
package at.aydin.lab.mongodb.legacy;
import org.bson.Document;
// Design Pattern: Data Mapper
// Zweck: Übersetzt manuell zwischen Fachobjekt und MongoDB Document.
public final class LegacyBookMapper {
public Document toDocument(LegacyBook b) {
return new Document("_id", b.id()).append("title", b.title()).append("year", b.year());
}
public LegacyBook fromDocument(Document d) {
return new LegacyBook(d.getString("_id"), d.getString("title"), d.getInteger("year"));
}
}
projects/24-mongodb/legacy/src/main/java/at/aydin/lab/mongodb/legacy/LegacyBookRepository.java
package at.aydin.lab.mongodb.legacy;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.model.ReplaceOptions;
import org.bson.Document;
import java.util.ArrayList;
import java.util.List;
import static com.mongodb.client.model.Filters.gte;
// Design Pattern: Repository
// Zweck: Mongo-Driver, BSON-Filter und manuelles Mapping werden hinter einer fachlichen API gekapselt.
public final class LegacyBookRepository {
private final MongoCollection<Document> collection;
private final LegacyBookMapper mapper;
public LegacyBookRepository(MongoCollection<Document> collection, LegacyBookMapper mapper) {
this.collection = collection;
this.mapper = mapper;
}
public void save(LegacyBook book) {
collection.replaceOne(new Document("_id", book.id()), mapper.toDocument(book), new ReplaceOptions().upsert(true));
}
public List<LegacyBook> findByYearGreaterThanEqual(int year) {
List<LegacyBook> result = new ArrayList<>();
for (Document document : collection.find(gte("year", year))) {
result.add(mapper.fromDocument(document));
}
return List.copyOf(result);
}
}
projects/24-mongodb/modern/src/main/java/at/aydin/lab/mongodb/modern/BookRepository.java
package at.aydin.lab.mongodb.modern;
import org.springframework.data.mongodb.repository.MongoRepository;
import java.util.*;
// Design Pattern: Repository
// Zweck: Query-Ableitung ersetzt manuelle Document-/Cursor-Verarbeitung.
public interface BookRepository extends MongoRepository<BookDocument, String> {
List<BookDocument> findByYearGreaterThanEqual(int year);
}
| ID | Ebene | Prüfung | erforderlicher Nachweis |
|---|---|---|---|
| 24-MONGODB-A01 | Integration/Contract | Bestehende Dokumente werden ohne Datenverlust gelesen. | Automatisierter Test und CI-Protokoll |
| 24-MONGODB-A02 | Integration/Contract | Neue Dokumente bleiben für Legacy-Leser kompatibel oder sind versioniert. | Automatisierter Test und CI-Protokoll |
| 24-MONGODB-A03 | Integration/Contract | ID-Typ ändert sich nicht unbemerkt. | Automatisierter Test und CI-Protokoll |
| 24-MONGODB-A04 | Integration/Contract | Kritische Queries nutzen erwartete Indizes. | Automatisierter Test und CI-Protokoll |
| 24-MONGODB-A05 | Integration/Contract | Unknown Fields brechen die Deserialisierung nicht unnötig. | Automatisierter Test und CI-Protokoll |
| 24-MONGODB-T01 | Unit | Fachlogik ohne Container oder externen Dienst testen. | Unit-Test |
| 24-MONGODB-T02 | Regression | Legacy- und Modern-Ergebnis für denselben Golden-Master-Vektor vergleichen. | Vergleichsreport |
| 24-MONGODB-T03 | Negative | Fehlerhafte, leere und grenzwertige Eingaben prüfen. | Negativtest |
| 24-MONGODB-T04 | Operations | Start, Health, Shutdown und Konfigurationsfehler prüfen. | Deployment-/Startprotokoll |
| 24-MONGODB-T05 | Database | Rollback, Constraints, Locking und Schema-Kompatibilität mit produktionsnahen Daten prüfen. | DB-Integrationstest |
| 24-MONGODB-F01 | Fokus | mapping, missing fields, query and index assumptions | Modulspezifischer Testreport |
| Risiko | Auswirkung | Gegenmaßnahme | Gate |
|---|---|---|---|
| document shape and mapping compatibility | NIEDRIG | mapping, missing fields, query and index assumptions | vor Cutover |
| Neue Framework-/Library-Laufzeitabhängigkeiten | MITTEL | SBOM, Lizenz-, CVE- und transitive Dependency-Prüfung im Online-Build | vor Release |
| Legacy-Verhalten war implizit an entfernte Library gekoppelt | MITTEL | Contract-/Golden-Master-Tests und gezielte Fehlerpfade | vor Abschaltung |
Keine zusätzlichen Ressourcen.
Repository-Port kann zwischen Legacy-Driver und Spring Data wechseln; Dokumentform bleibt während des Übergangs kompatibel.