Claude Code för korrekthet vid dataimport/export: praktiska steg

Vad går fel med CSV- och JSON-importer

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:

• Saknade obligatoriska fält (email, id, country) eller kolumner som bytt namn av någon som "rensade" filen
• Märkliga datum (01/02/03, 2024-13-01, Excels serienummer, blandade tidszoner)
• Extra kolumner eller oväntade nästlade JSON-objekt som lagts till av ett annat verktyg
• Typdrift ("00123" blir 123, true/false blir "yes"/"no")
• Dubbletter och nästan-dubbletter (samma id två gånger, eller samma person med olika skiftlägen)

Korrekthet ä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:

• Accepted: alla rader eller poster är giltiga och importeras
• Rejected: inget importeras eftersom filen inte är tillförlitlig (fel headers, dålig encoding, oläsbar JSON)
• Partially accepted: giltiga poster importeras, ogiltiga hoppas över med tydliga skäl

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.

Bestäm importkontraktet innan du skriver regler

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:

• Accepterade format och encoding (CSV-delimiter, JSON vs JSON Lines, nästlat stöd)
• Fältregler (required/optional/defaults, tillåtna värden)
• Normaliseringsregler (trim, case, datum-/nummerformat)
• Definition och hantering av dubbletter (upptäcktsomfång, valt beteende)
• Var validering sker (client, server eller båda)

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.

Valideringsregler som förblir läsbara och testbara

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:

• Normalize: omvandla rå input till en kanonisk form.
• Validate fields: små, återanvändbara kontroller per fält.
• Validate relationships: tvärfältkontroller med klara mål.
• Validate file rules: headers, dubbletter och versionsstöd.
• Test each layer: enhetstester för varje regel, plus ett par end-to-end-fixtures.

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.

Designa ett felrapporteringsformat som går att agera på

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.

Ett stabilt felobjekt

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_DATE
• message: en användarvänlig mening för UI
• path: 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 warning

Gö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.

Gruppering för UI och felsökning

Ä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.

Vad import-API:t bör returnera vid framgång och vid fel

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.

Returnera en tydlig importsammanfattning (varje gång)

Ä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äkningar
• totalRows (eller totalRecords för JSON)
• mode (till exempel: "createOnly", "upsert", eller "updateOnly")
• startedAt och finishedAt tidsstämplar
• en correlationId support kan fråga efter

Den 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.

Inkludera handlingsbara fel, plus ett sätt att hämta full rapport

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:

• plats: radnummer (CSV) eller JSON-pointer-liknande path (JSON)
• fältnamn
• felkod (maskinläsbar)
• meddelande (mänskligt läsbart)
• avvisat värde (var försiktig med känsliga data)

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.

Definiera idempotens så upprepade uppladdningar inte skapar dubbletter

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."

Använd rätt status för fel, men håll formen stabil

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.

Hur man använder Claude Code för att generera regler och exempel

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.

Steg för steg: fuzz-tester för CSV- och JSON-importer

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.

Bygg en seed-samling, sedan mutera

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:

• Encodingproblem: UTF-8 med BOM, ogiltiga byte-sekvenser, blandade normaliseringar
• Strukturproblem: saknade headers, extra kolumner/fält, fel delimiter, avslutande kommatecken
• Citat och ny-rader: oavslutade citat, inbäddade newlines, CRLF vs LF, inkonsekvent escaping
• Typkanter: enorma heltal, NaN/Infinity (JSON), tomma strängar vs null, blankstegspadding
• Storlek och gränser: väldigt långa fält, många rader, upprepade nycklar, djupt nästlade arrayer

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.

Definiera vad "pass" betyder, sedan lås det

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:

• Ingen krasch, timeout eller minnesspike över din gräns
• Tydliga fel med rad-/fältpekare (CSV) eller JSON-paths
• Stabila felkoder över körningar för samma fel
• Inga partiella skrivningar om du inte explicit stödjer partiell framgång
• Framgångsrika importer ger identiska resultat oavsett harmlös formatering (som blanksteg)

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.

Vanliga fällor som ger upprepade supportärenden

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:

• Odokumenterad "best effort"-parsning som ändras över tid
• Fel utan rad-/fältpekare och stabil felkod
• Allt-eller-inget-importer utan strikt vs partiell option
• UTF-8, BOM och osynliga tecken hanteras inkonsekvent
• Ändringar i felkoder som bryter klienthantering

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.

En snabb checklista innan du levererar en importerare

De flesta importproblem är små missmatchningar mellan vad användare tror filen betyder och vad ditt system accepterar. Behandla detta som en release-gate.

• Headers och fältnamn: bekräfta att nödvändiga kolumner finns, namn matchar regler och dubbletter avvisas. Bestäm vad du gör med extra kolumner (ignorera, varna, avvisa) och håll det konsekvent.
• Datatyper och format: bestäm hur du parser heltal vs decimaltal, booleans (true/false, 0/1, yes/no), datum och tidsstämplar (tidszonsregler). Föredra ett accepterat format per fält.
• Null och saknade värden: definiera vad tom sträng betyder per fält. Separera saknat fält, explicit null och blank text.
• Storleks- och säkerhetsgränser: sätt gränser för filstorlek, max rader och max fältlängd. Faila tidigt med ett tydligt meddelande.
• Deterministiska fel: samma dåliga input bör ge samma felkod och meddelandeform varje gång.

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.

Ett realistiskt exempel och nästa steg

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:

• Använd Claude Code för att generera valideringsregler, exempel på felaktiga rader och de felkoder/meddelanden du vill standardisera.
• Gör dessa exempel till automatiserade tester (inklusive fuzz-tester) så nya kantfall blir fallande tester, inte nya ärenden.
• Om du bygger med Koder.ai, använd planning mode för att skissa importkontraktet, generera validatorn och testerna, och iterera tills felutgångarna förblir konsekventa över CSV och JSON.