Modul 24 · Migration Deep Dive · Stufe 4 Daten und Transaktionen

MongoDB

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.

Data MapperRepository
3 → 2Produktionsdateien
50 → 18Java-Zeilen
1 → 1Testdateien
2 / 2Dependencies entfernt / neu
NIEDRIGRisiko · Score 1

Was sich konkret ändert

DimensionLegacyModernMigrationskonsequenz
Programmiermodellimperativ / ohne Framework-AnnotationenDocument, IdAnnotationen und Containerfunktionen werden nur dort eingesetzt, wo sie eine konkrete technische Verantwortung übernehmen.
Abhängigkeiten2 direkte Dependencies2 direkte Dependencies2 neu, 2 entfernt; Versionen und transitive Auswirkungen im erfolgreichen Online-Build prüfen.
Öffentliche API4 erkannte Methoden0 erkannte MethodenMethoden werden nach fachlicher Rolle gemappt; reine Bootstrap- und Framework-Methoden sind kein fachlicher Vertrag.
Datenmodellclass LegacyBookMapper, class LegacyBookRepository, record LegacyBookinterface BookRepository, record BookDocumentFeldnamen, IDs, Null-Semantik, Gleichheit und Serialisierungsform werden separat regressionstestet.
FehlerverhaltenLegacy-Exceptions und Rückgabewerteexplizitere Fach-/Framework-FehlerabbildungFehler dürfen nicht nur technisch übersetzt werden; Status, Ursache, Retrybarkeit und Client-Vertrag müssen erhalten oder versioniert werden.
TestsBestands- und Golden-Master-TestsUnit-, Slice-, Contract- und IntegrationstestsDer Modern-Pfad wird zuerst gegen denselben fachlichen Vektor geprüft und danach um neue technische Risiken ergänzt.
BetriebLegacy-Start/Lifecyclemodernes Packaging, Health und externe KonfigurationMigration mit produktionsnahen Daten, Backups, Restore-Probe und Query-/Lock-Monitoring absichern.
RollbackLegacy-Artefakt bleibt unverändertModern-Artefakt getrennt deploybarKein Rollback über Datenverlust: Schema, Nachrichten und verschlüsselte Daten müssen rückwärtslesbar oder durch Dual-Read abgesichert sein.

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.

Hauptrisiko und Testfokus

document shape and mapping compatibility

mapping, missing fields, query and index assumptions

Die Modernisierung gilt erst als abgeschlossen, wenn der fachliche Vertrag automatisiert belegt ist.

Verbindliches Code- und Rollenmapping

Die Zuordnung ist semantisch: Eine Legacy-Klasse kann in mehrere moderne Rollen zerlegt werden.

Legacy-Rolle / DateiModern-Rolle / DateiBedeutung
LegacyBook.javaBookDocument.javaBSON-Datenform wird annotiertes Spring-Data-Dokument.
LegacyBookMapper.java + LegacyBookRepository.javaBookRepository.javaManueller Mapper/Driver wird Repository-Abstraktion.

Legacy-Quellinventar

DateiTypAnnotationenöffentliche APIPatternZeilen
LegacyBook.javarecord LegacyBook4
LegacyBookMapper.javaclass LegacyBookMapperDocument toDocument(LegacyBook b)
LegacyBook fromDocument(Document d)
Data Mapper15
LegacyBookRepository.javaclass LegacyBookRepositoryvoid save(LegacyBook book)
List<LegacyBook> findByYearGreaterThanEqual(int year)
Repository31

Modern-Quellinventar

DateiTypAnnotationenöffentliche APIPatternZeilen
BookDocument.javarecord BookDocumentDocument, Id8
BookRepository.javainterface BookRepositoryRepository10

Dependency- und Laufzeitmigration

StatusDependencyVersionScopePrüfung
ENTFERNTorg.junit.jupiter:junit-jupiterBOM/ParenttestLegacy-Laufzeit entfällt oder wird durch Plattform/BOM ersetzt.
ENTFERNTorg.mongodb:mongodb-driver-syncBOM/ParentcompileLegacy-Laufzeit entfällt oder wird durch Plattform/BOM ersetzt.
NEUorg.springframework.boot:spring-boot-starter-data-mongodbBOM/ParentcompileNeue Laufzeit-/Testabhängigkeit; transitiv, lizenz- und security-seitig prüfen.
NEUorg.springframework.boot:spring-boot-starter-testBOM/ParenttestNeue Laufzeit-/Testabhängigkeit; transitiv, lizenz- und security-seitig prüfen.
Direkte POM-Daten ersetzen keinen erfolgreichen Online-Build mit transitiver SBOM- und CVE-Prüfung.

Vorher-/Nachher-Codebelege

Die folgenden Ausschnitte stammen direkt aus den enthaltenen Projekten. Dadurch ist sichtbar, welche Verantwortung tatsächlich verschoben wurde.

Legacy
LegacyBook.java
Modern
BookDocument.java

Migrationsbedeutung: BSON-Datenform wird annotiertes Spring-Data-Dokument.

Legacy-Code

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) {
}

Modern-Code

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) {
}
Technischen Unified Diff öffnen
--- 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) {
 }
Legacy
LegacyBookMapper.java + LegacyBookRepository.java
Modern
BookRepository.java

Migrationsbedeutung: Manueller Mapper/Driver wird Repository-Abstraktion.

Legacy-Code

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"));
    }
}

Legacy-Code

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);
    }
}

Modern-Code

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);
}

Umsetzungsplan mit Qualitäts-Gates

  1. Arbeitspaket 1
    Reale BSON-Dokumentformen und Mapper-Regeln inventarisieren. Nachweis: Commit/PR, automatisierter Test und aktualisierte Betriebsdokumentation.
  2. Arbeitspaket 2
    BookDocument mit expliziten Feldnamen und ID-Typ definieren. Nachweis: Commit/PR, automatisierter Test und aktualisierte Betriebsdokumentation.
  3. Arbeitspaket 3
    Spring Data Repository zunächst read-only einführen. Nachweis: Commit/PR, automatisierter Test und aktualisierte Betriebsdokumentation.
  4. Arbeitspaket 4
    LegacyBookMapper gegen neue Konvertierung mit Golden Documents vergleichen. Nachweis: Commit/PR, automatisierter Test und aktualisierte Betriebsdokumentation.
  5. Arbeitspaket 5
    Queries, Null-/fehlende Felder und Indizes testen. Nachweis: Commit/PR, automatisierter Test und aktualisierte Betriebsdokumentation.
  6. Arbeitspaket 6
    Schreibpfad erst nach Backfill-/Kompatibilitätsprüfung umstellen. Nachweis: Commit/PR, automatisierter Test und aktualisierte Betriebsdokumentation.

Konkreter Test- und Abnahmekatalog

IDEbenePrüfungerforderlicher Nachweis
24-MONGODB-A01Integration/ContractBestehende Dokumente werden ohne Datenverlust gelesen.Automatisierter Test und CI-Protokoll
24-MONGODB-A02Integration/ContractNeue Dokumente bleiben für Legacy-Leser kompatibel oder sind versioniert.Automatisierter Test und CI-Protokoll
24-MONGODB-A03Integration/ContractID-Typ ändert sich nicht unbemerkt.Automatisierter Test und CI-Protokoll
24-MONGODB-A04Integration/ContractKritische Queries nutzen erwartete Indizes.Automatisierter Test und CI-Protokoll
24-MONGODB-A05Integration/ContractUnknown Fields brechen die Deserialisierung nicht unnötig.Automatisierter Test und CI-Protokoll
24-MONGODB-T01UnitFachlogik ohne Container oder externen Dienst testen.Unit-Test
24-MONGODB-T02RegressionLegacy- und Modern-Ergebnis für denselben Golden-Master-Vektor vergleichen.Vergleichsreport
24-MONGODB-T03NegativeFehlerhafte, leere und grenzwertige Eingaben prüfen.Negativtest
24-MONGODB-T04OperationsStart, Health, Shutdown und Konfigurationsfehler prüfen.Deployment-/Startprotokoll
24-MONGODB-T05DatabaseRollback, Constraints, Locking und Schema-Kompatibilität mit produktionsnahen Daten prüfen.DB-Integrationstest
24-MONGODB-F01Fokusmapping, missing fields, query and index assumptionsModulspezifischer Testreport

Risikoregister des Moduls

RisikoAuswirkungGegenmaßnahmeGate
document shape and mapping compatibilityNIEDRIGmapping, missing fields, query and index assumptionsvor Cutover
Neue Framework-/Library-LaufzeitabhängigkeitenMITTELSBOM, Lizenz-, CVE- und transitive Dependency-Prüfung im Online-Buildvor Release
Legacy-Verhalten war implizit an entfernte Library gekoppeltMITTELContract-/Golden-Master-Tests und gezielte Fehlerpfadevor Abschaltung

Konfiguration und Ressourcen

Keine zusätzlichen Ressourcen.

Rollback und Koexistenz

Repository-Port kann zwischen Legacy-Driver und Spring Data wechseln; Dokumentform bleibt während des Übergangs kompatibel.

Abbruchkriterien

  • Fachlicher Golden-Master weicht ab.
  • Daten-, Nachrichten- oder API-Kompatibilität ist ungeklärt.
  • Fehlerquote, Latenz oder Ressourcenverbrauch überschreiten das vereinbarte Limit.
  • Monitoring oder Rückfallpfad ist nicht funktionsfähig.

Definition of Done

Direkte Arbeitslinks

⌂ Cockpit