Claude Code för att säkra korrekthet vid dataimport/export: definiera valideringsregler, konsekventa felformat och fuzz-tester för CSV/JSON-importer för att minska supportärenden från kantfall.
Importer misslyckas sällan för att koden är "fel". De misslyckas för att verkliga data är röriga, inkonsekventa och skapade av personer som aldrig såg dina antaganden.
CSV-problem handlar oftast om form och format. JSON-problem handlar oftast om betydelse och typer. Båda kan gå sönder på sätt som verkar små men ger förvirrande resultat.
Dessa problem återkommer ofta i supportärenden:
email, id, country) eller kolumner som bytt namn av någon som "rensade" filenKorrekthet är inte bara "hade det importerats". Du måste bestämma vilka utfall som är tillåtna, eftersom användare lägger märke till tysta misstag mer än högljudda fel.
De flesta team kan enas om tre utfall:
Kantfall blir omarbete när folk inte kan förstå vad som gick fel eller hur man snabbt åtgärdar det. Ett vanligt scenario: en kund laddar upp en CSV med 5 000 rader, importören säger "Invalid format", och de försöker tre gånger med slumpmässiga ändringar. Det blir flera ärenden plus någon hos er som försöker reproducera filen lokalt.
Sätt mål som minskar cykeln: färre omförsök, snabbare åtgärder, förutsägbara resultat. Innan du skriver regler, bestäm vad "partiell" betyder (och om du tillåter det), hur du rapporterar radnivåproblem, och vad användare ska göra härnäst (redigera filen, kartlägga fält, eller exportera en korrigerad version). Om du använder en vibe-coding-plattform som Koder.ai (koder.ai) för att snabbt generera validatorer och tester, är importkontraktet fortfarande vad som håller beteendet konsekvent när produkten utvecklas.
Innan du skriver en enda valideringsregel, bestäm vad "giltig input" betyder för din produkt. De flesta importbuggar beror på missmatchade förväntningar mellan vad användare laddar upp och vad ditt system tyst antar.
Börja med format, och var explicit. "CSV" kan betyda komma eller semikolon, en header-rad eller inte, UTF-8 eller "vad Excel producerade." För JSON, bestäm om du accepterar ett enda objekt, en array av poster eller JSON Lines (ett JSON-objekt per rad). Om du accepterar nästlad JSON, definiera vilka paths du läser och vilka du ignorerar.
Lås sedan fältkontraktet. För varje fält, bestäm om det är required, optional eller optional med default. Defaults är en del av kontraktet, inte en implementationdetalj. Om country saknas, defaultar du till tomt, väljer ett specifikt land eller avvisar raden?
Parsningsbeteende är där "toleranta" importer skapar långsiktiga problem. Bestäm i förväg hur strikt du är med att trimma mellanslag, normalisera case och acceptera varianter som "yes"/"true"/"1". Tolerans är okej om den är förutsägbar och dokumenterad.
Dubbletter är ett annat kontraktsval som påverkar korrekthet och förtroende. Definiera vad som räknas som dubblett (samma email, samma external_id, samma kombination av fält), var du upptäcker det (inom filen, mot befintliga data eller båda), och vad du gör när det händer (behåll första, behåll sista, slå ihop eller avvisa).
En kontraktschecklista du kan klistra in i en spec:
Exempel: import av "customers." Om email är den unika nyckeln, bestäm om " [email protected] " är samma som "[email protected]", om saknat email är tillåtet när external_id finns, och om dubbletter i filen ska avvisas även om databasen saknar match. När detta kontrakt är fixerat blir konsekvent beteende i UI och API mycket enklare, oavsett om du implementerar det i Koder.ai eller någon annanstans.
Röriga importer börjar ofta med en enda jättestor validate()-funktion. Ett renare tillvägagångssätt är lager med tydliga namn och små funktioner. Det gör ändringar lättare att granska och tester enklare att skriva.
Börja med fältnivåregler: kontroller som ett enda värde kan passera eller falla på egen hand (typ, intervall, längd, tillåtna värden, regex). Håll dem tråkiga och förutsägbara. Exempel: email matchar ett grundläggande emailmönster, age är ett heltal mellan 0 och 120, status är en av active|paused|deleted.
Lägg till tvärfält-regler bara där de behövs. Dessa kontroller beror på flera fält, och buggar gömmer sig här. Klassiska exempel: startDate måste vara före endDate, eller total är lika med subtotal + tax - discount. Skriv dessa regler så att de kan peka på specifika fält, inte bara "record invalid".
Separera regelkontroller för rader från filnivåregler. En radregel kollar en rad (CSV) eller ett objekt (JSON). En filregel kollar hela uppladdningen: nödvändiga headers finns, en unik nyckel upprepar sig inte över rader, kolumnantal matchar förväntat, eller filen deklarerar en stödjad version.
Normalisering bör vara explicit, inte "magisk". Bestäm vad du normaliserar innan du validerar, och dokumentera det. Vanliga exempel inkluderar trimning av mellanslag, Unicode-normalisering (så visuellt identiska tecken jämförs lika) och formatering av telefonnummer till ett konsekvent lagringsformat.
En struktur som förblir läsbar:
Versionera dina regler. Sätt ett schemaVersion (eller importprofil) i filen eller API-förfrågan. När du ändrar vad som är "giltigt" kan du ändå re-importera äldre exporter med den äldre versionen. Det enkla valet förhindrar många "det fungerade igår"-ärenden.
En bra importerare misslyckas på ett hjälpsamt sätt. Vaga fel leder till slumpmässiga omförsök och onödigt supportarbete. Ett tydligt felformat hjälper användare att snabbt fixa filen och hjälper dig att förbättra valideringen utan att bryta klienter.
Börja med en stabil felobjektsform och håll den konsekvent över CSV och JSON. Du kan använda Claude Code för att föreslå ett schema och några realistiska exempel, och sedan låsa det som en del av importkontraktet.
Behandla varje fel som en liten post med fält som inte ändras. Meddelandet kan utvecklas, men koden och platsen bör vara stabil.
code: en kort, stabil identifierare som REQUIRED_MISSING eller INVALID_DATEmessage: en användarvänlig mening för UIpath: var problemet är (JSON-pointer som /customer/email, eller ett kolumnnamn som email)row eller line: för CSV, inkludera 1-baserat radnummer (och eventuellt originalraden)severity: åtminstone error och warningGör felen handlingsbara. Inkludera vad du förväntade dig och vad du faktiskt såg, och när det är möjligt visa ett exempel som skulle bli godkänt. Till exempel: förväntat YYYY-MM-DD, fick 03/12/24.
Även om du returnerar en platt lista, inkludera tillräckligt med data för att gruppera fel per rad och per fält. Många UI vill visa "Rad 12 har 3 problem" och sedan markera varje kolumn. Supportteam gillar gruppering eftersom mönster blir uppenbara (t.ex. varje rad saknar country).
Ett kompakt svar kan se ut så här:
{
"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"
}
]
}
Planera för lokalisering utan att ändra felkoder. Håll code språkneutral och varaktig, och behandla message som utbytbar text. Om du senare lägger till messageKey eller översatta meddelanden kan gamla klienter fortfarande förlita sig på samma koder för filtrering, gruppering och analys.
För att undvika "mysterium-importer" bör ditt API-svar svara på två frågor: vad hände, och vad bör användaren göra härnäst.
Även när det finns fel, returnera en konsekvent sammanfattning så UI och supportverktyg kan hantera varje import på samma sätt.
Inkludera:
created, updated, skipped, failed räkningartotalRows (eller totalRecords för JSON)mode (till exempel: "createOnly", "upsert", eller "updateOnly")startedAt och finishedAt tidsstämplarcorrelationId support kan fråga efterDen correlationId är värd sin vikt. När någon rapporterar "det importerades inte" kan du hitta exakt körning och felrapport utan att gissa.
Dumpa inte 10 000 radfel i svaret. Returnera ett litet urval (t.ex. 20) som visar mönstret, och tillhandahåll ett separat sätt att hämta full rapport vid behov.
Gör varje fel specifikt och stabilt:
Exempel på svar (framgång med vissa radfel):
{
"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"
}
}
Notera fältet next. Även ett minimalt lyckat svar bör hjälpa produkten framåt: visa en granskningsskärm, erbjud en retry eller öppna den importerade samlingen.
Folk försöker igen. Nätverk fallerar. Om samma fil importeras två gånger vill du ha förutsägbara resultat.
Var explicit om idempotens: acceptera en idempotencyKey (eller beräkna en filhash), och returnera befintligt importId om förfrågan är en upprepning. Om ditt läge är upsert, definiera matchningsregeln (t.ex. "email är den unika nyckeln"). Om det är create-only, returnera "skipped" för dubbletter, inte "created again."
Om hela förfrågan är ogiltig (dålig auth, fel content type, oläsbar fil), faila snabbt och returnera status: "rejected" med en kort fellista. Om filen är giltig men har radnivåproblem, behandla det som ett slutfört jobb med failed > 0 så användare kan fixa och ladda upp igen utan att förlora sammanfattningen.
En användbar vana: be modellen att skriva kontraktet i ett strukturerat format, inte som löpande prosa. "Hjälpsamma stycken" hoppar ofta över detaljer som trim-regler, defaultvärden och om en tom cell betyder "saknas" eller "tom".
Använd en prompt som tvingar fram en tabell en människa snabbt kan granska och en utvecklare kan omvandla till kod. Be om varje fälts regel, pass- och fail-exempel, och en tydlig notering för allt som är tvetydigt (t.ex. tom sträng 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).
Efter första utkastet, skärp det genom att be om ett positivt och ett negativt exempel per regel. Det ökar täckningen av knepiga hörn som tomma strängar, endast blanksteg, saknade kolumner, null vs "null", väldigt stora heltal, vetenskaplig notation, dubblett-ID:n och extra JSON-fält.
För ett konkret scenario, tänk dig import av "customers" från CSV: email är required, phone är optional och signup_date defaultar till idag om den saknas. Modellen bör flagga en motsägelse om du också säger "signup_date är required". Den bör föreslå tester som import_customers_missing_email_returns_row_error och specificera felkod och meddelandeform du returnerar.
Gör en omgång till innan implementering: be modellen återge reglerna som en checklista och peka ut var defaults, required-fält och normalisering kan komma i konflikt. Denna granskningssteg fångar många beteenden som annars blir supportärenden.
Fuzz-testning stoppar "konstiga filer" från att bli supportärenden. Börja från ett litet set kända-bra CSV/JSON-filer, generera sedan tusentals lätt trasiga variationer och säkerställ att din importerare reagerar säkert och tydligt.
Börja med en liten seed-korpus av giltiga exempel som representerar verklig användning: minsta giltiga fil, en typisk fil och en stor fil. För JSON, inkludera ett objekt, många objekt och nästlade strukturer om du stödjer dem.
Lägg sedan till en automatisk mutator som vrider på en sak åt gången. Håll mutationer reproducerbara genom att logga den slumpmässiga seed så du kan spela upp fel.
Fuzz-dimensioner som fångar de flesta verkliga problem:
Stanna inte vid syntax. Lägg till semantisk fuzz också: byt liknande fält (email vs username), extrema datum, dubblett-ID:n, negativa kvantiteter eller värden som bryter enum.
Fuzz-tester hjälper bara om pass-kriterier är strikta. Din importerare ska aldrig krascha eller hänga, och felen ska vara konsekventa och handlingsbara.
Ett praktiskt uppsättning pass-regler:
Kör dessa tester i CI vid varje ändring. När du hittar ett fel, spara exakt fil som en fixture och lägg till ett regressions-test så det aldrig återkommer.
Om du använder Claude Code för detta arbete, be den generera seed-fixtures som matchar ditt kontrakt, en muteringsplan och förväntade felutdata. Du väljer fortfarande reglerna, men du får en bred testyta snabbt, särskilt för CSV-citatning och JSON-hörnfall.
De flesta importärenden kommer från oklara regler och otydlig feedback.
En vanlig fälla är "best effort"-parsning som inte dokumenteras. Om din importerare tyst trimmar blanksteg, accepterar både kommatecken och semikolon eller gissar datumformat, bygger användare arbetsflöden kring dessa gissningar. Sedan bryter en liten ändring eller en annan filgenerator allt. Välj beteendet, dokumentera det och testa det.
En annan återkommande orsak är generiska felmeddelanden. "Invalid CSV" eller "Bad request" tvingar användare att gissa. De laddar upp samma fil flera gånger och support ber om filen ändå. Fel bör peka på en rad, ett fält, ett tydligt skäl och en stabil kod.
Att avvisa hela filen för en dålig rad är också ett vanligt smärtpunktsfall. Ibland är det korrekt (t.ex. finansiella importer där partiell data är farligt). Många affärsimporter kan fortsätta och rapportera en sammanfattning, så länge du erbjuder ett explicit val som strict mode vs partial import.
Textkodningsproblem skapar envisa ärenden. UTF-8 är rätt standard, men verkliga CSV:er innehåller ofta en BOM, sneda citattecken eller icke-brytande mellanslag kopierade från kalkylblad. Hantera dessa konsekvent och rapportera vad du upptäckte så användare kan justera sina exportinställningar.
Slutligen, att ändra felkoder mellan releaser bryter klienter och automationer. Förbättra ordalydelsen om du vill, men behåll koder och betydelser stabila. Versionshantera dem bara när det verkligen behövs.
Fällor att gardera mot:
Exempel: en kund exporterar en CSV från Excel som lägger till en BOM och formaterar datum som 03/04/2026. Din importerare gissar MM/DD men kunden förväntade DD/MM. Om din felrapport inkluderar upptäckt format, exakt fält och föreslagen åtgärd kan användaren rätta det utan fram-och-tillbaka.
De flesta importproblem är små missmatchningar mellan vad användare tror filen betyder och vad ditt system accepterar. Behandla detta som en release-gate.
Ett praktiskt test: använd en avsiktligt rörig fil. Exempel: en CSV där headern förekommer två gånger (två "email"-kolumner), ett booleskt fält använder "Y" och ett datum är "03/04/05". Din importerare ska inte gissa. Den bör antingen tillämpa en dokumenterad mappningsregel eller avvisa med ett specifikt fel.
Två kontroller team ofta hoppar över:
För det första, verifiera att din importerare rapporterar fel med tillräcklig platsdetalj för att rätta källfilen. "Invalid date" är inte handlingsbart. "Rad 42, kolumn start_date: förväntat YYYY-MM-DD, fick 03/04/05" är det.
För det andra, kör samma ogiltiga fil två gånger och jämför resultaten. Om felordning ändras, koder ändras eller radnummer skiftar, tappar användare förtroendet. Deterministiskt beteende är tråkigt — och det är poängen.
En vanlig verklig import är kundorder från en spreadsheet-export. Någon exporterar en CSV från ett gammalt system, redigerar i Excel och laddar upp. De flesta ärenden uppstår när importören tyst "fixar" data eller när felmeddelandet inte säger vad som ska ändras.
Tänk dig en fil orders.csv med kolumnerna: order_id,customer_email,order_date,currency,total_amount.
Här är tre realistiskt felaktiga rader (som användaren skulle se dem):
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
Rad 2 har en ogiltig email och ett tvetydigt datumformat. Rad 3 saknar order_id, har en ogiltig valutakod (US istället för USD) och ett negativt belopp.
Om ditt API returnerar fel, håll formen konsekvent och specifik. Här är ett exempel på svar som stödjer partiell framgång:
{
"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]
}
}
Partiell framgång är viktigt eftersom användare inte borde behöva ladda upp hela filen igen. Ett enkelt retry-flöde är: fixa bara de misslyckade raderna, exportera en liten CSV som innehåller rad 2 och 3 och ladda upp på nytt. Din importerare bör behandla detta som idempotent när order_id finns, så "retry" uppdaterar samma poster istället för att skapa dubbletter.
För support är correlation_id det snabbaste sättet till diagnos. En supportagent kan be om det värdet, hitta importkörningen i loggar och bekräfta om parsern såg extra kolumner, fel delimiter eller oväntad encoding.
Nästa steg som gör detta repeterbart:
De flesta fel beror på röriga verkliga data, inte "fel kod". CSV-problem handlar oftast om struktur (headers, delimiter, quoting, encoding), medan JSON-problem oftare handlar om betydelse (typer, null vs tomt, oväntad nesting). Behandla båda som otrustade indata och validera mot ett explicit kontrakt.
Definiera tre utfall i förväg:
Välj ett standardbeteende (många produkter väljer partial) och gör det konsekvent i UI och API.
Skriv ner ett importkontrakt innan du börjar implementera:
Detta förhindrar "det fungerade igår"-överraskningar när beteendet ändras.
Standardisera på ett otvetydigt format per fält (t.ex. datum som YYYY-MM-DD). Om du accepterar varianter, gör det explicit och förutsägbart (t.ex. acceptera true/false/1/0, men inte alla kalkylarks-gissningar). Undvik att gissa tvetydiga datum som 01/02/03; kräva ISO eller avvisa med ett tydligt fel.
Bestäm:
Kombinera detta med idempotens så att samma uppladdning inte skapar dubbletter när användare kan göra om importer.
Använd lager i stället för en enda jättestor validate():
Små namngivna regler är lättare att testa och säkrare att förändra.
Returnera en stabil felstruktur med:
Alltid returnera en konsekvent sammanfattning, även vid fel:
Stöd retry-explicit:
idempotencyKey (eller använd en filhash)importId om samma förfrågan upprepasUtan detta kan vanliga användaromförsök skapa dubbletter.
Börja med ett fåtal kända-bra seed-filer och generera sedan många små mutationer (en ändring i taget):
NaN/Infinity i JSON)Ett fuzz-test "passerar" när importeraren aldrig kraschar/hänger och returnerar deterministiska, handlingsbara fel.
Vanliga fallgropar:
Åtgärda genom att dokumentera beteendet, rapportera precisa fel och hålla felkoder stabila eller versionshantera dem.
Innan release—en snabb checklista:
code (stabil identifierare)message (lättläst)path/field (kolumnnamn eller JSON-pointer)row/line (för CSV)severity (error vs warning)Gör felen handlingsbara genom att inkludera vad som förväntades och vad som faktiskt fanns när det är möjligt.
created, updated, skipped, failed, plus totalRows/totalRecordsstatus (success, rejected, completed_with_errors)startedAt, finishedAt)correlationId för support/felsökningFör stora filer: inkludera ett litet errorsSample och ett sätt att hämta fullständig rapport senare.
Testa med en avsiktligt rörig fil och kontrollera att fel är tillräckligt detaljerade för att användaren ska fixa källfilen.