Große Datenimporte in Laravel: Validierung, Fortschritt und Fehler

Ein Import ist mehr als ein Datei-Upload #

Eine CSV-Datei mit 100.000 Produktdatensätzen soll Preise und Artikelinformationen aktualisieren. Der Upload funktioniert, doch bei der Verarbeitung bricht die Anfrage ab. Drei Fragen stehen dann sofort im Raum:

• Wurden bereits Daten gespeichert?
• Kann die Datei erneut hochgeladen werden?
• Welche Zeilen waren fehlerhaft?

Der Ablauf sollte sie beantworten können, bevor der erste große Import startet.

Ein sinnvoller Aufbau trennt Annahme, Prüfung, Verarbeitung und Ergebnis. Die folgenden Schritte beschreiben einen Architekturvorschlag für einen Produktimport. Paketgröße, Fehlerregeln und Datenmodell müssen zum tatsächlichen Projekt passen.

Datei und Datensätze getrennt prüfen #

Beim Upload werden Berechtigung, Dateigröße und erwartetes Format geprüft. Die Datei wird außerhalb öffentlich erreichbarer Verzeichnisse gespeichert und erhält einen Importdatensatz mit Eigentümer, Status und Speicherort. Jobs bekommen die Import-ID und eine Referenz auf ihren Datenabschnitt; die gesamte Datei gehört nicht in die Queue-Nachricht.

Danach folgt die Strukturprüfung: Stimmen Zeichencodierung, Trennzeichen und Spaltennamen? Beim Einlesen müssen CSV-Felder korrekt geparst werden, einschließlich zitierter Zeilenumbrüche. Ein einfaches Aufteilen an jedem Zeilenumbruch würde solche Datensätze beschädigen.

Fachliche Regeln werden pro Datensatz geprüft:

• Hat der Artikel eine eindeutige Nummer?
• Ist der Preis gültig?
• Existiert die zugehörige Kategorie?

Eine Vorschau kann zeigen, welche Felder zugeordnet werden und wie viele Artikel neu angelegt oder geändert würden. Unbekannte Spalten oder ungültige Beträge sollten zu verständlichen Meldungen führen.

Begrenzte Arbeitspakete statt einer langen Anfrage #

Der HTTP-Aufruf bestätigt die Annahme mit einer Import-ID. Ein Worker liest die Datei anschließend schrittweise, ohne sämtliche Datensätze gleichzeitig im Speicher zu halten. Für die Verteilung lassen sich vorab geprüfte Abschnitte in einer Zwischentabelle oder in separaten Dateien ablegen. So muss nicht jeder Job die Originaldatei erneut vom Anfang durchsuchen.

Ein Paket von beispielsweise 500 Datensätzen ist ein Ausgangspunkt für Messungen, keine allgemeingültige Empfehlung. Entscheidend sind Speicherbedarf, Laufzeit, Datenbanklast und mögliche API-Aufrufe. Wenn Produkte von zuvor angelegten Kategorien abhängen, müssen diese Schritte geordnet werden; beliebige Parallelisierung wäre dann falsch.

Laravel bietet Queues für Hintergrundjobs und Job-Batches zur Gruppierung mehrerer Jobs. Die Dokumentation zu Job-Batches in Laravel 12 beschreibt Fortschritt, Fehlerbehandlung und Wiederholungen. Prüfe die passenden APIs für die in deinem Projekt eingesetzte Version.

Fortschritt aus dauerhaftem Zustand ableiten #

Die Oberfläche benötigt mehr als einen drehenden Ladeindikator. Sinnvolle Zustände sind „Wird geprüft“, „Bereit zur Verarbeitung“, „Läuft“, „Mit Fehlern abgeschlossen“ und „Abgebrochen“. Solange die Anzahl der Datensätze noch nicht bekannt ist, sollte sie die aktuelle Phase anzeigen, statt eine scheinbar genaue Prozentzahl zu berechnen.

Speichere die Anzahl gelesener, erfolgreich verarbeiteter und abgelehnter Datensätze am Import beziehungsweise an seinen Paketen. Der Fortschritt eines Laravel-Batches zählt Jobs; bei unterschiedlich großen Paketen entspricht er nicht automatisch dem Anteil verarbeiteter Zeilen.

Ein Status-Endpunkt liefert diese Werte an die Oberfläche und prüft, ob die anfragende Person den Import sehen darf. Bei Wiederholungen darf ein Paket nicht erneut zum Erfolgszähler addiert werden. Dazu wird sein Abschluss zusammen mit den lokalen Datenänderungen transaktional festgehalten.

Fehler korrigieren und sicher wiederholen #

Ein ungültiger Preis ist ein fachlicher Fehler. Eine vorübergehend nicht erreichbare Datenbank ist ein technischer Fehler. Fachliche Fehler brauchen Zeilennummer, Feld, Ursache und eine Korrekturmöglichkeit; technische Fehler können unter geeigneten Bedingungen erneut versucht werden. Ein Fehlerbericht sollte nur die dafür benötigten Daten enthalten und demselben Zugriffsschutz wie der Import unterliegen.

Lege vorab fest, ob gültige Zeilen trotz einzelner Fehler übernommen werden dürfen. Werden Pakete separat gespeichert, gibt es keine automatische Rücknahme des gesamten Imports. Muss die neue Datenbasis als Ganzes erscheinen, kann eine vorgelagerte Staging-Struktur mit abschließender Freigabe geeigneter sein.

Wiederholbare Verarbeitung benötigt stabile fachliche Schlüssel, etwa Lieferant und externe Artikelnummer, sowie passende Eindeutigkeitsregeln in der Datenbank. Ein erneuter Versuch aktualisiert denselben Artikel, statt ihn doppelt anzulegen. Auch konkurrierende Importe müssen geregelt werden, damit ein älterer Lauf nicht aktuelle Preise überschreibt.

Welche Fälle vor dem Einsatz getestet werden sollten #

• Eine gültige Datei erzeugt die erwarteten Artikel und Änderungen.
• Fehlende Spalten, ungültige Werte und doppelte Artikelnummern werden verständlich gemeldet.
• Ein Job bricht nach einem bereits gespeicherten Paket ab und wird erneut ausgeführt.
• Große Dateien bleiben innerhalb der gemessenen Speicher- und Laufzeitgrenzen.
• Mehrere Importe derselben Datenquelle folgen der festgelegten Reihenfolge.
• Unberechtigte Personen können weder Dateien noch Status oder Fehlerberichte abrufen.

Vereinbare außerdem, wann Originaldateien, Zwischendaten und Fehlerberichte gelöscht werden. Die verantwortliche Person muss einen fehlgeschlagenen Import finden und gezielt fortsetzen können, ohne dafür auf Serverprotokolle angewiesen zu sein.

Für wiederkehrende Datenübernahmen unterstütze ich dich mit Laravel-Backends und Schnittstellenentwicklung. Wenn noch offen ist, welche Systeme welche Daten liefern sollen, hilft der Ratgeber Schnittstellen planen.