Claude Code für Korrektheit bei Datenimport/-export: praktische Schritte

Was bei CSV- und JSON-Importen schiefgeht

Importe scheitern selten, weil der Code „falsch“ ist. Sie scheitern, weil reale Daten unordentlich, inkonsistent sind und von Menschen stammen, die nie Ihre Annahmen gesehen haben.

CSV-Probleme betreffen meist Form und Format. JSON-Probleme betreffen meist Bedeutung und Typen. Beides kann auf Arten brechen, die nur wie Kleinigkeiten aussehen, aber zu verwirrenden Ergebnissen führen.

Diese Probleme tauchen immer wieder in Support-Tickets auf:

• Fehlende Pflichtfelder (email, id, country) oder Spalten, die jemand beim "Bereinigen" umbenannt hat
• Seltsame Datumsangaben (01/02/03, 2024-13-01, Excel-Seriennummern, gemischte Zeitzonen)
• Zusätzliche Spalten oder unerwartete verschachtelte JSON-Objekte, die ein anderes Tool hinzugefügt hat
• Typabweichungen ("00123" wird zu 123, true/false wird zu "yes"/"no")
• Duplikate und Nahe-Duplikate (gleiche id zweimal oder dieselbe Person mit unterschiedlicher Groß-/Kleinschreibung)

Korrektheit ist nicht nur „wurde importiert“. Sie müssen entscheiden, welche Ergebnisse erlaubt sind, denn Nutzer bemerken stille Fehler mehr als laute Fehlschläge.

Die meisten Teams können sich auf drei Outcomes einigen:

• Accepted: alle Zeilen oder Datensätze sind gültig und wurden importiert
• Rejected: nichts wird importiert, weil die Datei nicht vertrauenswürdig ist (falsche Header, ungültige Codierung, unlesbares JSON)
• Partially accepted: gültige Datensätze werden importiert, ungültige werden übersprungen mit klaren Gründen

Edge-Cases führen zu Mehrarbeit, wenn Leute nicht schnell sagen können, was schiefgelaufen ist oder wie sie es beheben. Ein typisches Szenario: Ein Kunde lädt eine CSV mit 5.000 Zeilen hoch, der Importer sagt „Invalid format“, und er probiert dreimal mit zufälligen Änderungen. Das wird zu mehreren Tickets plus jemandem bei Ihnen, der versucht, die Datei lokal zu reproduzieren.

Setzen Sie Ziele, die den Zyklus verkürzen: weniger Wiederholungen, schnellere Behebungen, vorhersehbare Ergebnisse. Bevor Sie Regeln schreiben, entscheiden Sie, was „partiell“ bedeutet (und ob Sie es erlauben), wie Sie zeilenbezogene Probleme melden und was Nutzer als Nächstes tun sollen (Datei bearbeiten, Felder zuordnen oder eine korrigierte Version exportieren). Wenn Sie eine Modell-gestützte Plattform wie Koder.ai (Koder.ai) verwenden, um Validatoren und Tests schnell zu generieren, bleibt der Importvertrag trotzdem der Punkt, der das Verhalten konsistent hält, während das Produkt sich weiterentwickelt.

Entscheiden Sie den Importvertrag, bevor Sie Regeln schreiben

Bevor Sie eine einzelne Validierungsregel schreiben, definieren Sie, was „gültige Eingabe" für Ihr Produkt bedeutet. Die meisten Import-Bugs entstehen durch unterschiedliche Erwartungen zwischen dem, was Nutzer hochladen, und dem, was Ihr System stillschweigend annimmt.

Beginnen Sie mit Formaten und seien Sie explizit. „CSV" kann Komma oder Semikolon bedeuten, eine Header-Zeile oder nicht, UTF-8 oder „was auch immer Excel produziert hat“. Für JSON entscheiden Sie, ob Sie ein einzelnes Objekt, ein Array von Datensätzen oder JSON Lines (ein JSON-Objekt pro Zeile) akzeptieren. Wenn Sie verschachteltes JSON akzeptieren, definieren Sie, welche Pfade Sie lesen und welche Sie ignorieren.

Dann sperren Sie den Feldvertrag ab. Für jedes Feld entscheiden Sie, ob es required, optional oder optional mit Default ist. Defaults sind Teil des Vertrags, nicht eine Implementierungs-Detail. Wenn country fehlt, defaulten Sie auf leer, wählen ein bestimmtes Land oder lehnen Sie die Zeile ab?

Parsing-Verhalten ist der Punkt, an dem „tolerante" Importe langfristigen Ärger erzeugen. Entscheiden Sie im Voraus, wie strikt Sie beim Trimmen von Leerzeichen, Normalisierung von Groß-/Kleinschreibung und beim Akzeptieren von Varianten wie "yes"/"true"/"1" sind. Toleranz ist in Ordnung, wenn sie vorhersehbar und dokumentiert ist.

Duplikate sind ebenfalls eine Vertragsentscheidung, die Korrektheit und Vertrauen beeinflusst. Definieren Sie, was als Duplikat zählt (gleiche E-Mail, gleiche external_id oder eine Kombination von Feldern), wo Sie es erkennen (innerhalb der Datei, gegenüber bestehenden Daten oder beides) und was Sie tun, wenn es passiert (erstes behalten, letztes behalten, mergen oder ablehnen).

Eine Contract-Checklist, die Sie in ein Spec kopieren können:

• Akzeptierte Formate und Encoding (CSV-Delimiter, JSON vs JSON Lines, Unterstützung für verschachtelte Strukturen)
• Feldregeln (required/optional/defaults, erlaubte Werte)
• Normalisierungsregeln (trimmen, Groß-/Kleinschreibung, Datums-/Zahlenformate)
• Duplikatsdefinition und -behandlung (Erkennungsumfang, gewähltes Verhalten)
• Validierungsort (Client, Server oder beides)

Beispiel: Import von „customers“. Wenn email der eindeutige Schlüssel ist, entscheiden Sie, ob " [email protected] " gleich "[email protected]" ist, ob fehlende E-Mail erlaubt ist, wenn external_id vorhanden ist, und ob Duplikate innerhalb der Datei abgelehnt werden sollen, selbst wenn die Datenbank keinen Treffer hat. Sobald dieser Vertrag feststeht, ist konsistentes Verhalten über UI und API hinweg viel einfacher, egal ob Sie ihn in Koder.ai oder anderswo implementieren.

Validierungsregeln, die lesbar und testbar bleiben

Unordentliche Importe beginnen oft mit einer einzigen gigantischen validate()-Funktion. Ein sauberer Ansatz sind geschichtete Regeln mit klaren Namen und kleinen Funktionen. Das macht Änderungen einfacher zu reviewen und Tests einfacher zu schreiben.

Beginnen Sie mit feldbezogenen Regeln: Prüfungen, die ein einzelner Wert alleine bestehen oder nicht bestehen kann (Typ, Bereich, Länge, erlaubte Werte, Regex). Halten Sie sie langweilig und vorhersehbar. Beispiele: email passt zu einem einfachen E‑Mail-Muster, age ist eine Ganzzahl zwischen 0 und 120, status ist eines von active|paused|deleted.

Fügen Sie Cross-Field-Regeln nur dort hinzu, wo sie relevant sind. Diese Prüfungen hängen von mehreren Feldern ab und dort verstecken sich Bugs. Klassische Beispiele: startDate muss vor endDate liegen oder total muss subtotal + tax - discount entsprechen. Schreiben Sie diese Regeln so, dass sie auf spezifische Felder verweisen können, nicht nur „Datensatz ungültig".

Trennen Sie Record-Level-Regeln von File-Level-Regeln. Eine Record-Level-Regel prüft eine Zeile (CSV) oder ein Objekt (JSON). Eine File-Level-Regel prüft den gesamten Upload: erforderliche Header vorhanden, ein eindeutiger Schlüssel wiederholt sich nicht, Spaltenanzahl entspricht Erwartung oder die Datei deklariert eine unterstützte Version.

Normalisierung sollte explizit sein, nicht „magisch“. Entscheiden Sie, was Sie normalisieren, bevor Sie validieren, und dokumentieren Sie es. Übliche Beispiele sind Trimmen von Leerzeichen, Unicode-Normalisierung (damit visuell identische Zeichen gleich verglichen werden) und Formatierung von Telefonnummern in ein konsistentes Speicherformat.

Eine Struktur, die lesbar bleibt:

• Normalize: rohe Eingabe in eine kanonische Form transformieren.
• Validate fields: kleine, wiederverwendbare Prüfungen pro Feld.
• Validate relationships: Cross-Field-Prüfungen mit klaren Zielen.
• Validate file rules: Header, Duplikate und Versionssupport.
• Test each layer: Unit-Tests für jede Regel plus ein paar End-to-End-Fixtures.

Versionieren Sie Ihre Regeln. Legen Sie ein schemaVersion (oder Import-„Profil") in der Datei oder der API-Anfrage ab. Wenn Sie ändern, was „gültig" bedeutet, können Sie ältere Exporte weiterhin mit der älteren Version re-importieren. Diese eine Entscheidung verhindert viele „ging gestern noch"-Tickets.

Entwerfen Sie ein Fehlermeldungsformat, nach dem man handeln kann

Ein guter Importer schlägt auf eine hilfreiche Weise fehl. Vage Fehler führen zu zufälligen Wiederholungen und vermeidbarer Supportarbeit. Ein klares Fehlerformat hilft Nutzern, die Datei schnell zu korrigieren, und hilft Ihnen, die Validierung zu verbessern, ohne Clients zu brechen.

Beginnen Sie mit einer stabilen Fehlerobjekt-Form und halten Sie sie für CSV und JSON konsistent. Sie können Claude Code verwenden, um ein Schema und ein paar realistische Beispiele vorzuschlagen und es dann als Teil des Importvertrags festschreiben.

Ein stabiles Fehlerobjekt

Behandle jeden Fehler als kleines Record mit Feldern, die sich nicht ändern. Die Meldung kann sich weiterentwickeln, aber code und location sollten stabil bleiben.

• code: eine kurze, stabile Kennung wie REQUIRED_MISSING oder INVALID_DATE
• message: ein für Menschen verständlicher Satz für die UI
• path: wo das Problem ist (JSON-Pointer wie /customer/email oder ein Spaltenname wie email)
• row oder line: für CSV, 1-basierte Zeilennummer (optional die Originalzeile)
• severity: mindestens error und warning

Machen Sie Fehler handlungsfähig. Geben Sie an, was Sie erwartet haben und was Sie tatsächlich gesehen haben, und zeigen Sie wenn möglich ein Beispiel, das bestehen würde. Zum Beispiel: erwartet YYYY-MM-DD, erhalten 03/12/24.

Gruppierung für UI und Debugging

Auch wenn Sie eine flache Liste zurückgeben, fügen Sie genügend Daten hinzu, um Fehler nach Zeile und Feld zu gruppieren. Viele UIs wollen „Zeile 12 hat 3 Probleme" und dann jede Spalte hervorheben. Support-Teams mögen Gruppierungen, weil Muster offensichtlich werden (z. B. fehlt in jeder Zeile country).

Eine kompakte Antwort könnte so aussehen:

{
  "importId": "imp_123",
  "status": "failed",
  "errors": [
    {
      "code": "INVALID_DATE",
      "message": "Signup date must be in YYYY-MM-DD.",
      "path": "signup_date",
      "row": 12,
      "severity": "error",
      "expected": "YYYY-MM-DD",
      "actual": "03/12/24"
    },
    {
      "code": "UNKNOWN_FIELD",
      "message": "Column 'fav_colour' is not recognized.",
      "path": "fav_colour",
      "row": 1,
      "severity": "warning"
    }
  ]
}

Planen Sie Lokalisierung, ohne Fehlercodes zu verändern. Behalten Sie code sprachneutral und dauerhaft bei und behandeln Sie message als austauschbaren Text. Wenn Sie später messageKey oder übersetzte Meldungen hinzufügen, können alte Clients weiterhin dieselben Codes für Filterung, Gruppierung und Analyse verwenden.

Was die Import-API bei Erfolg und Fehler zurückgeben sollte

Um „mysteriöse Imports“ zu vermeiden, sollte Ihre API zwei Fragen beantworten: Was ist passiert und was soll der Nutzer als Nächstes tun?

Geben Sie immer eine klare Import-Zusammenfassung zurück

Auch wenn Fehler auftreten, geben Sie eine konsistente Zusammenfassung zurück, damit UI und Support-Tools jede Importausführung gleich behandeln können.

Enthalten Sie:

• created, updated, skipped, failed Counts
• totalRows (oder totalRecords für JSON)
• mode (z. B. "createOnly", "upsert" oder "updateOnly")
• startedAt und finishedAt Zeitstempel
• eine correlationId, nach der der Support fragen kann

Diese correlationId ist viel wert. Wenn jemand meldet „es wurde nicht importiert", können Sie den genauen Lauf und den Fehlerbericht finden, ohne zu raten.

Einschließlich handlungsfähiger Fehler und einer Möglichkeit, den vollen Bericht abzurufen

Laden Sie nicht 10.000 Zeilenfehler in die Antwort. Geben Sie eine kleine Stichprobe zurück (z. B. 20), die das Muster zeigt, und bieten Sie einen separaten Weg an, den vollständigen Bericht bei Bedarf abzurufen.

Machen Sie jeden Fehler spezifisch und stabil:

• location: Zeilennummer (CSV) oder JSON-pointer-ähnlicher Pfad (JSON)
• Feldname
• Fehlercode (maschinenlesbar)
• message (menschenlesbar)
• abgelehnter Wert (achten Sie auf sensitive Daten)

Beispiel für eine Antwort (erfolgreich mit einigen Zeilenfehlern):

{
  "importId": "imp_01HZY...",
  "correlationId": "c_9f1f2c2a",
  "status": "completed_with_errors",
  "summary": {
    "totalRows": 1200,
    "created": 950,
    "updated": 200,
    "skipped": 10,
    "failed": 40
  },
  "errorsSample": [
    {
      "row": 17,
      "field": "email",
      "code": "invalid_format",
      "message": "Email must contain '@'.",
      "value": "maria.example.com"
    }
  ],
  "report": {
    "hasMore": true,
    "nextPageToken": "p_002"
  },
  "next": {
    "suggestedAction": "review_errors"
  }
}

Beachten Sie das next-Feld. Schon ein minimales Erfolgs-Payload sollte dem Produkt helfen weiterzumachen: eine Review-Seite anzeigen, einen Retry anbieten oder die importierte Sammlung öffnen.

Definieren Sie Idempotenz, damit wiederholte Uploads nicht doppelt erzeugen

Menschen versuchen es erneut. Netzwerke fallen aus. Wenn dieselbe Datei zweimal importiert wird, wollen Sie vorhersehbare Ergebnisse.

Seien Sie explizit bei Idempotenz: Akzeptieren Sie einen idempotencyKey (oder berechnen Sie einen File-Hash) und geben Sie die bestehende importId zurück, wenn die Anfrage ein Duplikat ist. Wenn Ihr Modus Upsert ist, definieren Sie die Matching-Regel (z. B. „E-Mail ist der eindeutige Schlüssel"). Wenn es create-only ist, geben Sie für Duplikate „skipped" zurück, nicht „created again".

Verwenden Sie den richtigen Status für Fehler, behalten Sie aber die Form stabil

Wenn die ganze Anfrage ungültig ist (schlechte Auth, falscher Content-Type, unlesbare Datei), schlagen Sie schnell fehl und geben status: "rejected" mit einer kurzen Fehlerliste zurück. Wenn die Datei syntaktisch gültig ist, aber zeilenbezogene Probleme hat, behandeln Sie sie als abgeschlossenen Job mit failed > 0, damit Nutzer korrigieren und neu hochladen können, ohne die Zusammenfassung zu verlieren.

Wie man Claude Code verwendet, um Regeln und Beispiele zu generieren

Eine nützliche Gewohnheit: Lassen Sie das Modell den Vertrag in einem strukturierten Format schreiben, nicht als Fließtext. „Hilfreiche Absätze" überspringen oft Details wie Trimmregeln, Default-Werte und ob eine leere Zelle „fehlend" oder „leer" bedeutet.

Verwenden Sie eine Aufforderung, die das Modell zwingt, eine Tabelle auszugeben, die ein Mensch schnell überprüfen kann und ein Entwickler leicht in Code umsetzen kann. Fordern Sie für jedes Feld die Regel, Pass-/Fail-Beispiele und eine explizite Notiz zu allem Mehrdeutigen (z. B. leerer String vs null).

You are helping design an importer for CSV and JSON.
Output a Markdown table with columns:
Field | Type | Required? | Normalization | Validation rules | Default | Pass examples | Fail examples
Rules must be testable (no vague wording).
Then output:
1) A list of edge cases to test (CSV + JSON).
2) Proposed test names with expected result (pass/fail + error code).
Finally, list any contradictions you notice (required vs default, min/max vs examples).

Nach dem ersten Entwurf verschärfen Sie ihn, indem Sie für jede Regel ein positives und ein negatives Beispiel verlangen. Das erhöht die Abdeckung für knifflige Ecken wie leere Strings, nur aus Leerzeichen bestehende Werte, fehlende Spalten, null vs "null", sehr große Ganzzahlen, wissenschaftliche Notation, doppelte IDs und zusätzliche JSON-Felder.

Für ein konkretes Szenario: Import von „customers" aus CSV: email ist required, phone ist optional, und signup_date defaultet auf heute, falls fehlt. Das Modell sollte einen Widerspruch melden, wenn Sie zusätzlich sagen „signup_date ist required". Es sollte Tests wie import_customers_missing_email_returns_row_error vorschlagen und Fehlercode sowie Nachrichtenform angeben.

Machen Sie eine zusätzliche Review-Runde vor der Implementierung: Lassen Sie das Modell die Regeln als Checkliste wiedergeben und aufzeigen, wo Defaults, required-Felder und Normalisierung in Konflikt geraten könnten. Diese Review fängt viele ticketwürdige Verhalten ein.

Schritt für Schritt: Fuzz-Tests für CSV- und JSON-Importe

Fuzz-Testing verhindert, dass „seltsame Dateien" Support-Tickets verursachen. Beginnen Sie mit einer kleinen Menge bekannter guter CSV/JSON-Dateien und generieren Sie dann tausende leicht kaputter Variationen, um sicherzustellen, dass Ihr Importer sicher und verständlich reagiert.

Erstellen Sie ein Seed-Set und mutieren Sie es

Starten Sie mit einer kleinen Seed-Kollektion gültiger Beispiele, die reale Nutzung repräsentieren: die kleinste gültige Datei, eine typische Datei und eine große Datei. Für JSON: ein Objekt, viele Objekte und verschachtelte Strukturen, falls unterstützt.

Fügen Sie dann einen automatisierten Mutator hinzu, der jeweils nur eine Änderung vornimmt. Halten Sie Mutationen reproduzierbar, indem Sie den Zufalls-Seed protokollieren, damit Sie Fehler wiederholen können.

Fuzz-Dimensionen, die die meisten realen Probleme erfassen:

• Encoding-Probleme: UTF-8 mit BOM, ungültige Byte-Sequenzen, gemischte Normalisierung
• Strukturprobleme: fehlende Header, zusätzliche Spalten/Felder, falsches Trennzeichen, nachgestellte Kommata
• Quoting und Newlines: nicht geschlossene Anführungszeichen, eingebettete Newlines, CRLF vs LF, inkonsistente Escapes
• Typen-Grenzfälle: riesige Ganzzahlen, NaN/Infinity (JSON), leere Strings vs null, Leerzeichen-Padding
• Größe und Limits: sehr lange Felder, viele Zeilen, wiederholte Keys, tief verschachtelte Arrays

Hören Sie nicht bei Syntax auf. Fügen Sie semantische Fuzz-Variationen hinzu: ähnliche Felder vertauschen (email vs username), extreme Daten, doppelte IDs, negative Mengen oder Werte, die Enums verletzen.

Definieren Sie, was „pass“ bedeutet, und sperren Sie es ein

Fuzz-Tests helfen nur, wenn die Pass-Kriterien streng sind. Ihr Importer sollte niemals abstürzen oder hängen, und Fehler sollten konsistent und handlungsfähig sein.

Eine praktische Menge an Pass-Regeln:

• Kein Absturz, keine Timeouts oder Memory-Spitzen über Ihr Limit
• Klare Fehler mit Zeilen-/Feld-Pointern (CSV) oder JSON-Pfaden
• Stabile Fehlercodes bei gleichen Fehlschlägen über Runs hinweg
• Keine teilweisen Schreibvorgänge, sofern Sie kein partielles Ergebnis ausdrücklich unterstützen
• Erfolgreiche Importe liefern identische Ergebnisse, unabhängig von harmlosen Formatierungen (z. B. Leerzeichen)

Führen Sie diese Tests in CI bei jeder Änderung aus. Wenn Sie einen Fehler finden, speichern Sie die exakte Datei als Fixture und fügen Sie einen Regressions-Test hinzu, damit er nie zurückkehrt.

Wenn Sie Claude Code einsetzen, lassen Sie es Seed-Fixtures erzeugen, einen Mutationsplan und die erwarteten Fehlerausgaben. Sie wählen weiterhin die Regeln, aber Sie erhalten schnell eine große Testfläche, besonders für CSV-Quoting und JSON-Eckenfälle.

Häufige Fallen, die wiederkehrende Support-Tickets verursachen

Die meisten Import-Tickets entstehen durch unklare Regeln und wenig hilfreiches Feedback.

Eine häufige Falle ist "best effort"-Parsing, das nicht dokumentiert ist. Wenn Ihr Importer still Leerzeichen trimmt, sowohl Komma als auch Semikolon akzeptiert oder Datumsformate rät, bauen Nutzer Workflows um diese Annahmen. Eine kleine Änderung oder ein anderes Export-Tool bricht dann alles. Wählen Sie das Verhalten, dokumentieren Sie es und testen Sie es.

Ein weiterer häufiger Fehler sind generische Fehlermeldungen. "Invalid CSV" oder "Bad request" zwingt Nutzer zum Raten. Sie laden dieselbe Datei fünf Mal hoch, und der Support fragt trotzdem nach der Datei. Fehler sollten auf eine Zeile, ein Feld, einen klaren Grund und einen stabilen Code verweisen.

Das komplette Ablehnen der Datei wegen einer fehlerhaften Zeile ist ebenfalls schmerzhaft. Manchmal ist das korrekt (z. B. Finanzimporte). Viele Business-Exporte können fortfahren und eine Zusammenfassung liefern, sofern Sie eine explizite Wahl wie strict mode vs partial import anbieten.

Text-Encoding-Probleme erzeugen hartnäckige Tickets. UTF-8 ist die richtige Voreinstellung, aber echte CSVs enthalten oft BOM, typografische Anführungszeichen oder nicht-brechende Leerzeichen aus Tabellenkalkulationen. Behandeln Sie diese konsistent und melden Sie, was erkannt wurde, damit Nutzer ihre Exporteinstellungen korrigieren können.

Schließlich brechen geänderte Fehlercodes zwischen Releases Clients und Automationen. Verbessern Sie Formulierungen ruhig, aber behalten Sie Codes und Bedeutungen stabil. Versionieren Sie nur, wenn es wirklich nötig ist.

Traps, gegen die Sie von Anfang an schützen sollten:

• Undokumentiertes "best effort"-Parsing, das sich über die Zeit ändert
• Fehler ohne Zeilen-/Feld-Pointer und ohne stabilen Fehlercode
• Alles-oder-nichts-Importe ohne strict- vs partial-Option
• UTF-8, BOM und unsichtbare Zeichen nicht einheitlich behandeln
• Änderung von Fehlercodes, die Client-Handling kaputtmachen

Beispiel: Ein Kunde exportiert eine CSV aus Excel, die einen BOM hinzufügt und Datumswerte als 03/04/2026 formatiert. Ihr Importer rät MM/DD, aber der Kunde erwartet DD/MM. Wenn Ihr Fehlerbericht das erkannte Format, das genaue Feld und eine vorgeschlagene Korrektur enthält, kann der Nutzer die Datei ohne Hin und Her reparieren.

Kurze Checkliste vor dem Versand eines Importers

Die meisten Importprobleme sind kleine Missverständnisse zwischen dem, was Nutzer unter einer Datei verstehen, und dem, was Ihr System akzeptiert. Behandeln Sie dies als Release-Gate.

• Header und Feldnamen: Bestätigen Sie, dass erforderliche Spalten vorhanden sind, Namen Ihren Regeln entsprechen und Duplikate abgelehnt werden. Entscheiden Sie, was mit zusätzlichen Spalten passiert (ignorieren, warnen, fehlschlagen) und halten Sie es konsistent.
• Datentypen und Formate: Legen Sie fest, wie Sie Ganzzahlen vs Dezimalzahlen, Booleans (true/false, 0/1, yes/no), Daten und Zeitstempel (Zeitzonenregeln) parsen. Bevorzugen Sie ein akzeptiertes Format pro Feld.
• Null- und fehlende Werte: Definieren Sie, was ein leerer String pro Feld bedeutet. Trennen Sie fehlendes Feld, explizites null und leeren Text.
• Größen- und Sicherheitslimits: Setzen Sie Limits für Dateigröße, maximale Zeilenanzahl und maximale Feldlänge. Schlagen Sie früh mit einer klaren Nachricht fehl.
• Deterministische Fehler: Dieselbe schlechte Eingabe sollte jedes Mal denselben Fehlercode und dieselbe Nachrichtenform ergeben.

Ein praktischer Test: Verwenden Sie eine absichtlich unordentliche Datei. Beispiel: eine CSV, in der Header doppelt vorkommt (zwei "email"-Spalten), ein Boolean-Feld benutzt "Y" und ein Datum ist "03/04/05". Ihr Importer sollte nicht raten. Er sollte eine dokumentierte Mapping-Regel anwenden oder mit einem spezifischen Fehler ablehnen.

Zwei Checks, die Teams oft überspringen:

Erstens: Stellen Sie sicher, dass Ihr Importer Fehler mit genügend Ortsangabe meldet, um die Quell-Datei zu korrigieren. "Invalid date" ist nicht handlungsfähig. "Zeile 42, Spalte start_date: erwartet YYYY-MM-DD, erhalten 03/04/05" ist es.

Zweitens: Führen Sie dieselbe ungültige Datei zweimal aus und vergleichen Sie die Ergebnisse. Wenn sich die Fehlerreihenfolge ändert, Codes ändern oder Zeilennummern verschieben, verlieren Nutzer das Vertrauen. Deterministisches Verhalten ist langweilig — und genau darum geht es.

Ein realistisches Beispiel-Szenario und nächste Schritte

Ein häufiger realer Import sind Kundenbestellungen, die aus einem Tabellenexport stammen. Jemand exportiert eine CSV aus einem alten System, bearbeitet sie in Excel und lädt sie hoch. Die meisten Tickets entstehen, wenn der Importer Daten still „korrigiert" oder wenn die Fehlermeldung nicht sagt, was zu ändern ist.

Stellen Sie sich eine Datei namens orders.csv mit den Spalten order_id,customer_email,order_date,currency,total_amount vor.

Hier sind drei realistische fehlerhafte Zeilen (wie der Nutzer sie sehen würde):

order_id,customer_email,order_date,currency,total_amount
A-1001,[email protected],2026-01-05,USD,129.99
A-1002,not-an-email,01/06/2026,USD,49.00
,[email protected],2026-01-07,US, -10

Zeile 2 hat eine ungültige E-Mail und ein mehrdeutiges Datumsformat. Zeile 3 fehlt order_id, hat einen nicht unterstützten Währungscode (US statt USD) und einen negativen Betrag.

Wenn Ihre API Fehler zurückgibt, halten Sie die Form stabil und spezifisch. Hier ein Beispiel für eine Antwort, die partielle Erfolge unterstützt:

{
  "correlation_id": "imp_20260109_7f3a9d",
  "import_id": "ord_01HZZ...",
  "status": "partial_success",
  "summary": {
    "total_rows": 3,
    "imported_rows": 1,
    "failed_rows": 2
  },
  "errors": [
    {
      "row_number": 2,
      "field": "customer_email",
      "code": "invalid_email",
      "message": "Email must contain a valid domain.",
      "value": "not-an-email"
    },
    {
      "row_number": 2,
      "field": "order_date",
      "code": "invalid_date_format",
      "message": "Use ISO-8601 (YYYY-MM-DD).",
      "value": "01/06/2026"
    },
    {
      "row_number": 3,
      "field": "order_id",
      "code": "required",
      "message": "order_id is required.",
      "value": ""
    },
    {
      "row_number": 3,
      "field": "currency",
      "code": "unsupported_currency",
      "message": "Allowed values: USD, EUR, GBP.",
      "value": "US"
    },
    {
      "row_number": 3,
      "field": "total_amount",
      "code": "must_be_positive",
      "message": "total_amount must be greater than 0.",
      "value": " -10"
    }
  ],
  "retry": {
    "mode": "upload_failed_only",
    "failed_row_numbers": [2, 3]
  }
}

Partieller Erfolg ist wichtig, weil Nutzer nicht die ganze Datei erneut hochladen sollten. Ein einfacher Retry-Flow ist: nur die fehlerhaften Zeilen reparieren, eine kleine CSV mit Zeilen 2 und 3 exportieren und erneut hochladen. Ihr Importer sollte dies als idempotent behandeln, wenn order_id vorhanden ist, sodass "retry" dieselben Datensätze aktualisiert statt Duplikate zu erstellen.

Für den Support ist correlation_id der schnellste Weg zur Diagnose. Ein Support-Agent kann nach diesem Wert fragen, den Importlauf in Logs finden und bestätigen, ob der Parser zusätzliche Spalten, ein falsches Trennzeichen oder unerwartetes Encoding gesehen hat.

Nächste Schritte, die das reproduzierbar machen:

• Verwenden Sie Claude Code, um Validierungsregeln, Beispiel-fehlerhafte Zeilen und die Fehlercodes/-nachrichten zu generieren, die Sie standardisieren wollen.
• Machen Sie aus diesen Beispielen automatisierte Tests (inkl. Fuzz-Tests), damit neue Eckenfälle zu fehlenden Tests statt zu neuen Tickets werden.
• Wenn Sie mit Koder.ai bauen, nutzen Sie den Planning-Mode, um den Importvertrag zu entwerfen, Validator und Tests zu generieren und iterieren Sie, bis die Fehlerausgabe für CSV und JSON konsistent bleibt.