डेटा इम्पोर्ट/एक्सपोर्ट की सटीकता के लिए Claude Code: मान्यकरण नियम, संगत त्रुटि स्वरूप और CSV/JSON इम्पोर्ट्स के लिए फ़ज़ टेस्ट बनाकर कोने‑के सपोर्ट टिकट कम करें।
इम्पोर्ट्स ज़्यादातर इसलिए फेल नहीं होते कि कोड "गलत" है। वे फेल होते हैं क्योंकि असल डेटा गन्दा, असंगत और उन मान्यताओं से उत्पन्न होता है जो डेटा बनाने वाले ने कभी नहीं देखीं।
CSV समस्याएँ आमतौर पर आकार और फ़ॉर्मैटिंग के बारे में होती हैं। JSON समस्याएँ अक्सर अर्थ और प्रकार से जुड़ी होती हैं। दोनों ऐसे तरीकों से टूट सकते हैं जो मामूली दिखते हैं पर भ्रमित परिणाम पैदा करते हैं।
ये मुद्दे सपोर्ट टिकटों में बार‑बार आते हैं:
सटीकता सिर्फ "इम्पोर्ट हुआ या नहीं" नहीं है। आपको तय करना होगा कि कौनसे परिणाम स्वीकार्य हैं, क्योंकि यूज़र्स मौन गलतियों से ज़्यादा शोर वाली विफलताओं को नोटिस करते हैं।
अधिकांश टीमें तीन परिणामों पर सहमत हो सकती हैं:
एज‑केसेस तब रीवर्क बन जाते हैं जब लोग नहीं समझ पाते कि क्या गलत हुआ या उसे कैसे जल्दी ठीक करें। एक सामान्य परिदृश्य: ग्राहक 5,000 पंक्तियों वाला CSV अपलोड करता है, इम्पोर्टर कहता है “Invalid format”, और वे यादृच्छिक बदलाव करके तीन बार रीट्राई करते हैं। इससे कई टिकट बनते हैं और आपकी तरफ़ से कोई फ़ाइल लोकली reproduce करने की कोशिश करता है।
चक्र को घटाने वाले लक्ष्य सेट करें: कम retries, तेज़ फिक्स, पूर्वानुमेय परिणाम। नियम लिखने से पहले तय करें कि "partial" का क्या मतलब है (और क्या आप इसे.allow करते हैं), आप रो‑लेवल मुद्दों को कैसे रिपोर्ट करेंगे, और यूज़र्स को अगला कदम क्या करना चाहिए (फ़ाइल एडिट करें, फ़ील्ड मैप करें, या सही की हुई फ़ाइल एक्सपोर्ट करें)। यदि आप Koder.ai जैसी प्लेटफ़ॉर्म का उपयोग कर रहे हैं तो भी इम्पोर्ट कॉन्ट्रैक्ट वही व्यवहार उत्पाद के विकास के साथ सुसंगत रखता है।
एक single validation rule लिखने से पहले स्पष्ट करें कि आपके उत्पाद के लिए "वैध इनपुट" का क्या मतलब है। अधिकांश इम्पोर्ट बग्स यूज़र द्वारा अपलोड किए गए और आपके सिस्टम की मौन मान्यताओं के बीच मिसमैच होते हैं।
फ़ॉर्मैट से शुरू करें और स्पष्ट रहें। “CSV” का मतलब कॉमा या सेमीकोलन हो सकता है, हेडर रो हो सकता है या न हो, UTF-8 हो सकता है या "Excel ने जो बनाया"। JSON के लिए तय करें कि आप एक सिंगल ऑब्जेक्ट स्वीकार करते हैं, रिकॉर्ड्स की एरे, या JSON Lines (लाइन‑प्रति‑लाइन JSON)। यदि आप नेस्टेड JSON स्वीकार करते हैं, तो परिभाषित करें कि आप कौनसे पाथ पढ़ेंगे और किन्हें अनदेखा करेंगे।
फिर फ़ील्ड कॉन्ट्रैक्ट लॉक करें। हर फ़ील्ड के लिए तय करें कि वह required है, optional है, या default के साथ optional है। डिफ़ॉल्ट्स कॉन्ट्रैक्ट का हिस्सा हैं, न कि implementation detail। यदि country गायब है, क्या आप खाली डिफ़ॉल्ट करेंगे, किसी विशिष्ट देश को चुनेंगे, या रो को reject करेंगे?
पार्सिंग व्यवहार वह जगह है जहाँ "tolerant" इम्पोर्ट्स लंबे समय में दर्द पैदा करते हैं। पहले तय करें कि आप trimming spaces, केस नॉर्मलाइज़ेशन, और ऐसे वैरिएंट स्वीकार करने में कितने कड़े हैं जैसे "yes"/"true"/"1"। सहिष्णुता ठीक है अगर यह पूर्वानुमेय और दस्तावेजीकृत हो।
डुप्लिकेट्स भी एक कॉन्ट्रैक्ट निर्णय है जो सटीकता और भरोसे को प्रभावित करता है। तय करें कि डुप्लिकेट क्या गिना जाएगा (same email, same external_id, या फ़ील्ड्स का कोई कॉम्बिनेशन), कहाँ पता चला जाएगा (फ़ाइल के भीतर, मौजूदा डेटा के खिलाफ, या दोनों) और आप इसके साथ क्या करेंगे (पहला रखें, आख़िरी रखें, merge करें, या reject करें)।
एक कॉन्ट्रैक्ट चेकलिस्ट जिसे आप स्पेस में पेस्ट कर सकते हैं:
उदाहरण: "customers" इम्पोर्ट करते समय। यदि email यूनिक की है, तो तय करें कि \" [email protected] \" \"[email protected]\" के बराबर है या नहीं, क्या missing email तब मान्य है जब external_id मौजूद हो, और क्या फ़ाइल के अंदर डुप्लिकेट्स को reject किया जाना चाहिए भले ही डेटाबेस में मैच न हो। एक बार यह कॉन्ट्रैक्ट फिक्स हो जाए, UI और API दोनों में सुसंगत व्यवहार आसान होता है—चाहे आप इसे Koder.ai में लागू करें या कहीं और।
गंदे इम्पोर्ट्स अक्सर एक बड़े validate() फ़ंक्शन से शुरू होते हैं। एक साफ़ तरीका है लेयर्ड नियमों का उपयोग करना जिनके नाम स्पष्ट हों और फ़ंक्शन छोटे हों। इससे बदलाव आसान होते हैं और टेस्ट लिखना भी सरल।
फ़ील्ड‑लेवल नियमों से शुरू करें: एक वैल्यू अकेले पास या फेल कर सकती है (टाइप, रेंज, लंबाई, अनुमत मान, regex)। उन्हें साधारण और अनुमाननीय रखें। उदाहरण: email एक बेसिक ईमेल पैटर्न से मेल खाता है, age 0 और 120 के बीच एक integer है, status में से एक हो active|paused|deleted।
जहाँ जरूरी हो वहां ही क्रॉस‑फ़ील्ड नियम जोड़ें। ये चेक एक से अधिक फ़ील्ड्स पर निर्भर करते हैं, और बग यहाँ छिपते हैं। क्लासिक उदाहरण: startDate को endDate से पहले होना चाहिए, या total बराबर होना चाहिए subtotal + tax - discount के। इन नियमों को इस तरह लिखें कि वे विशिष्ट फ़ील्ड्स की ओर इशारा कर सकें, केवल "record invalid" कहने के बजाय।
रिकॉर्ड‑लेवल नियमों को फ़ाइल‑लेवल नियमों से अलग रखें। रिकॉर्ड‑लेवल नियम एक रो (CSV) या एक ऑब्जेक्ट (JSON) की जाँच करते हैं। फ़ाइल‑लेवल नियम पूरी अपलोड की जाँच करते हैं: आवश्यक हेडर्स मौजूद हैं, यूनिक की पंक्तियों में दोहराव नहीं है, कॉलम गिनती अपेक्षाओं से मेल खाती है, या फ़ाइल ने एक समर्थित वर्शन घोषित किया है।
नॉर्मलाइज़ेशन को "जादू" नहीं बनाएं। तय करें कि आप वैलिडेट करने से पहले क्या नॉर्मलाइज़ करते हैं और इसे दस्तावेज़ में डालें। सामान्य उदाहरणों में spaces ट्रिम करना, यूनिकोड नॉर्मलाइज़ेशन (ताकि दृश्य रूप से समान कैरेक्टर्स एक‑समान तुलना दें), और फोन नंबर को एक सुसंगत स्टोरेज फ़ॉर्मैट में फॉर्मैट करना शामिल है।
एक पठनीय संरचना:
अपने नियमों का वर्शनिंग करें। फ़ाइल या API रिक्वेस्ट में schemaVersion (या इम्पोर्ट "प्रोफ़ाइल") रखें। जब आप "वैध" का अर्थ बदलते हैं, तब भी आप पुराने एक्सपोर्ट्स को पुराने वर्शन के साथ री‑इम्पोर्ट कर सकेंगे। यह एक विकल्प बहुत सारी "कल तक काम कर रहा था" वाली शिकायतों को रोकता है।
एक अच्छा इम्पोर्टर मददगार तरीके से फेल होता है। अस्पष्ट त्रुटियाँ यादृच्छिक retries और अनावश्यक सपोर्ट कार्य की ओर ले जाती हैं। एक स्पष्ट त्रुटि फॉर्मैट यूज़र्स को फ़ाइल जल्दी ठीक करने में मदद करता है, और आपको बिना क्लाइंट ब्रेक किए वैलिडेशन में सुधार करने में मदद मिलती है।
एक स्थिर त्रुटि ऑब्जेक्ट शेप के साथ शुरू करें और CSV तथा JSON दोनों में इसका पालन रखें। Claude Code का उपयोग करके आप एक schema और कुछ यथार्थवादी उदाहरण प्रस्तावित कर सकते हैं, फिर उसे इम्पोर्ट कॉन्ट्रैक्ट का हिस्सा बनाकर लॉक करें।
प्रत्येक त्रुटि को एक छोटा रिकॉर्ड मानें जिनमें ऐसे फ़ील्ड हों जो नहीं बदलते। मैसेज बदल सकता है, पर code और location स्थिर रखें।
code: एक छोटा, स्थिर पहचानकर्ता जैसे REQUIRED_MISSING या INVALID_DATEmessage: UI के लिए मानव‑अनुकूल वाक्यpath: जहाँ समस्या है (JSON pointer जैसे /customer/email, या कॉलम नाम जैसे email)row या line: CSV के लिए 1‑आधारित रो नंबर शामिल करें (और वैकल्पिक रूप से मूल लाइन)severity: कम से कम error और warningत्रुटियों को कार्रवाई योग्य बनाएं। क्या अपेक्षित था और वास्तविक में क्या देखा गया यह शामिल करें, और जब संभव हो एक पास करने वाला उदाहरण दिखाएँ। उदाहरण: अपेक्षित YYYY-MM-DD, मिला 03/12/24।
यहाँ तक कि यदि आप फ्लैट सूची लौटाते भी हैं, तो रो और फ़ील्ड द्वारा त्रुटियों को ग्रुप करने के लिए पर्याप्त डेटा शामिल करें। कई UI चाहती हैं "Row 12 has 3 issues" और फिर हर कॉलम को हाइलाइट करती हैं। सपोर्ट टीमें भी ग्रुपिंग पसंद करती हैं क्योंकि पैटर्न स्पष्ट होते हैं (उदाहरण के लिए, हर रो country गायब है)।
एक कॉम्पैक्ट रिस्पॉन्स इस तरह दिख सकता है:
{
"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"
}
]
}
त्रुटि कोड को लोकलाइज़ किए बिना प्लान करें। code भाषा‑तटस्थ और टिकाऊ रखें, और message को बदलने योग्य मानें। यदि बाद में आप messageKey या अनुवादित संदेश जोड़ते हैं, तो पुराने क्लाइंट्स अभी भी उन्हीं कोड्स पर भरोसा कर सकते हैं।
"मिस्ट्री इम्पोर्ट्स" से बचने के लिए, आपका API रिस्पॉन्स दो सवालों का उत्तर दे: क्या हुआ, और यूज़र को अगला कदम क्या उठाना चाहिए।
भले ही त्रुटियाँ हों, एक सुसंगत सारांश लौटाएँ ताकि UI और सपोर्ट टूलिंग हर इम्पोर्ट को एक ही तरीके से हैंडल कर सकें।
शामिल करें:
created, updated, skipped, failed काउंट्सtotalRows (या JSON के लिए totalRecords)mode (उदाहरण: "createOnly", "upsert", या "updateOnly")startedAt और finishedAt टाइमस्टैम्पcorrelationId जिसे सपोर्ट पूछ सकेवह correlationId बहुत उपयोगी है। जब कोई रिपोर्ट करता है "यह इम्पोर्ट नहीं हुआ", आप सही रन और त्रुटि रिपोर्ट बिना अनुमान लगाए ढूंढ सकते हैं।
हज़ारों रो त्रुटियों को सीधे रिस्पॉन्स में न डालें। एक छोटा सैम्पल (जैसे 20) लौटाएँ जो पैटर्न दिखाए, और पूरा रिपोर्ट अलग से फ़ेच करने का तरीका दें।
हर त्रुटि को विशिष्ट और स्थिर बनाएं:
उदाहरण रिस्पॉन्स शुद्धता के साथ कुछ रो फ़ेल होने पर:
{
"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"
}
}
next फ़ील्ड का ध्यान रखें। एक न्यूनतम सफलता पेलोड भी उत्पाद को आगे बढ़ाने में मदद करनी चाहिए: समीक्षा स्क्रीन दिखाएँ, रीट्राई का विकल्प दें, या इम्पोर्ट की गई कलेक्शन खोलें।
लोग रिट्राई करते हैं। नेटवर्क फेल होते हैं। यदि वही फ़ाइल दो बार इम्पोर्ट हो, तो आप पूर्वानुमेय परिणाम चाहते हैं।
idempotency के बारे में स्पष्ट रहें: एक idempotencyKey स्वीकार करें (या फ़ाइल हैश की गणना करें), और यदि रिक्वेस्ट दोहराई गई है तो मौजूदा importId लौटाएँ। यदि आपका मोड upsert है, तो मैचिंग नियम परिभाषित करें (उदा. "email यूनिक की है")। यदि create-only है, तो duplicates के लिए "skipped" लौटाएँ, "created again" न करें।
यदि पूरी रिक्वेस्ट ही अमान्य है (खराब auth, गलत content type, पढ़ने योग्य नहीं फ़ाइल), तो फेल फ़ास्ट करें और status: "rejected" के साथ एक छोटा error list लौटाएँ। यदि फ़ाइल वैध है पर रो‑लेवल समस्याएँ हैं, तो इसे failed > 0 के साथ एक completed job मानें ताकि यूज़र्स बिना सारांश खोए फिक्स और री‑अपलोड कर सकें।
एक उपयोगी आदत: मॉडल से कॉन्ट्रैक्ट को संरचित फ़ॉर्म में लिखवाएँ, सिर्फ़ परिच्छेदों में नहीं। "मददगार पैराग्राफ़" अक्सर trimming नियम, डिफ़ॉल्ट मान, और क्या ख़ाली सेल "missing" या "empty" माना जाएगा जैसे विवरण छोड़ देते हैं।
ऐसा prompt उपयोग करें जो एक तालिका ज़ोर दे जिसे इंसान जल्दी रिव्यू कर सके और डेवलपर सीधे कोड में बदल सके। हर फ़ील्ड के नियम, पास और फेल उदाहरण, और किसी भी अस्पष्टता के लिए स्पष्ट नोट माँगें (उदाहरण: खाली स्ट्रिंग बनाम 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).
पहले ड्राफ्ट के बाद, हर नियम के लिए एक सकारात्मक और एक नकारात्मक उदाहरण माँगें। इससे empty strings, whitespace‑only values, missing columns, null बनाम "null", बहुत बड़े integers, वैज्ञानिक संकेतन, duplicate IDs, और अतिरिक्त JSON फ़ील्ड जैसे कोने‑के‑मामलों पर कवरेज बढ़ेगा।
एक ठोस परिदृश्य के लिए: "customers" CSV इम्पोर्ट करते समय: email आवश्यक है, phone वैकल्पिक है, और signup_date गायब होने पर आज की तारीख को डिफ़ॉल्ट करें। मॉडल को विरोधाभास फ़्लैग करना चाहिए यदि आप साथ ही कहते हैं कि "signup_date आवश्यक है"। इसे ऐसे टेस्ट सुझाने चाहिए जैसे import_customers_missing_email_returns_row_error और स्पष्ट रूप से बताना चाहिए कि कौनसा error code और message आप लौटाएंगे।
इम्प्लिमेंटेशन से पहले एक और पास करें: मॉडल से कहें कि नियमों को चेकलिस्ट के रूप में फिर से बताये और जहाँ डिफ़ॉल्ट्स, required फ़ील्ड्स, और नॉर्मलाइज़ेशन टकरा सकते हैं वहाँ बताएं। वह रिव्यू स्टेप बहुत सारी टिकट‑योग्य व्यवहार को पकड़ लेता है।
फ़ज़ परीक्षण यह रोकता है कि "अजीब फाइलें" सपोर्ट टिकट बनें। एक छोटे सेट ज्ञात‑अच्छे CSV/JSON फाइलों से शुरू करें, फिर हजारों हल्के-से‑टूटी वैरिएशन्स जनरेट करें और सुनिश्चित करें कि आपका इम्पोर्टर सुरक्षित और स्पष्ट तरीके से प्रतिक्रिया दे।
सही उपयोग को दर्शाने वाले छोटे सीड कॉर्पस से शुरू करें: सबसे छोटी वैध फ़ाइल, एक सामान्य फ़ाइल, और एक बड़ी फ़ाइल। JSON के लिए, एक ऑब्जेक्ट, कई ऑब्जेक्ट्स, और नेस्टेड संरचनाएँ शामिल करें यदि आप उन्हें सपोर्ट करते हैं।
फिर एक ऑटोमेटेड म्यूटेटर जोड़ें जो एक बार में एक चीज़ बदलता है। यादृच्छिक सीड लॉग करके म्यूटेशन्स को पुनरुत्पादन योग्य रखें ताकि विफलताएँ री‑रन की जा सकें।
फ़ज़ आयाम जो अधिकांश वास्तविक‑विश्व समस्याएँ पकड़ते हैं:
सिंटैक्स पर ही मत रुकें। सेमांटिक फ़ज़ भी जोड़ें: समान फ़ील्ड्स को स्वैप करें (email vs username), चरम तिथियाँ, duplicate IDs, negative quantities, या enum का उल्लंघन करने वाले मान।
फ़ज़ टेस्ट तभी मददगार होते हैं जब पास मानदंड कड़े हों। आपका इम्पोर्टर कभी क्रैश या हैंग नहीं होना चाहिए, और त्रुटियाँ सुसंगत तथा कार्रवाई योग्य होनी चाहिए।
एक व्यावहारिक पास नियम सेट:
इन टेस्ट्स को हर परिवर्तन पर CI में चलाएँ। जब आप विफलता पाते हैं, उस सटीक फ़ाइल को फ़िक्सचर के रूप में सेव करें और एक रेग्रेशन टेस्ट जोड़ें ताकि वह दोबारा न आए।
यदि आप इस कार्य में Claude Code का उपयोग करते हैं, तो उसे अपनी कॉन्ट्रैक्ट के मैच करने वाले सीड फ़िक्स्चर्स, म्यूटेशन प्लान, और अपेक्षित त्रुटि आउटपुट जेनरेट करने के लिए कहें। नियम आप चुनते हैं, पर आप तेज़ी से व्यापक टेस्ट सरफेस पाएंगे, विशेषकर CSV क्वोटिंग और JSON कोने‑के‑मामलों के लिए।
अधिकांश इम्पोर्ट टिकट अस्पष्ट नियमों और बेकार फीडबैक से आते हैं।
एक सामान्य जाल "best effort" पार्सिंग है जो लिखित नहीं है। यदि आपका इम्पोर्टर spaces चुपके से ट्रिम करता है, कॉमा और सेमीकोलन दोनों स्वीकार करता है, या तारीखों का अनुमान लगाता है, तो यूज़र्स उन अनुमानों पर वर्कफ़्लो बना लेते हैं। फिर एक छोटा बदलाव या एक अलग फ़ाइल जेनरेटर सब कुछ तोड़ देता है। व्यवहार चुनें, दस्तावेज़ बनाएं, और परीक्षण करें।
एक और सामान्य समस्या generic error message है। "Invalid CSV" या "Bad request" यूज़र्स को अनुमान लगाने पर मजबूर करते हैं। वे वही फ़ाइल पाँच बार अपलोड करते हैं, और सपोर्ट को फिर भी फ़ाइल माँगनी पड़ती है। त्रुटियों को रो, फ़ील्ड, स्पष्ट कारण और स्थिर कोड बताना चाहिए।
एक ही बुरी रो के लिए पूरी फ़ाइल फेल करना भी अक्सर तकलीफ़ देता है। कभी‑कभी यह सही होता है (उदा. वित्तीय इम्पोर्ट जहाँ partial डेटा खतरनाक है)। कई व्यवसायिक इम्पोर्ट्स जारी रह सकते हैं और सारांश रिपोर्ट कर सकते हैं, बशर्ते आप strict mode बनाम partial import जैसा स्पष्ट विकल्प दें।
टेक्स्ट एन्कोडिंग समस्याएँ जिद्दी टिकट बनाती हैं। UTF-8 सही डिफ़ॉल्ट है, पर असल CSV अक्सर BOM, curly quotes, या स्प्रेडशीट से कॉपी किए गए non‑breaking spaces शामिल करते हैं। इन्हें सुसंगत तरीके से हैंडल करें और आपने जोDetected किया उसे रिपोर्ट करें ताकि यूज़र अपने एक्सपोर्ट सेटिंग्स ठीक कर सकें।
अंत में, रिलीज़ के बीच त्रुटि कोड बदलना क्लाइंट्स और ऑटोमेशन तोड़ देता है। अगर आप wording बदलना चाहते हैं तो कोड न बदलें। केवल तब वर्शनिंग करें जब वाकई ज़रूरी हो।
रोकथाम योग्य जाल:
उदाहरण: ग्राहक Excel से CSV एक्सपोर्ट करता है, जो BOM जोड़ देता है और तारीखें 03/04/2026 के रूप में फॉर्मैट होती हैं। आपका इम्पोर्टर MM/DD मानता है, पर ग्राहक DD/MM उम्मीद कर रहा था। यदि आपकी त्रुटि रिपोर्ट में पता चला फ़ॉर्मैट, सटीक फ़ील्ड और सुझाया गया फिक्स शामिल है, तो यूज़र बिना बैक‑एंड बातचीत के इसे ठीक कर सकता है।
अधिकांश इम्पोर्ट समस्याएँ उस छोटे मिसमैच से होती हैं जो यूज़र फ़ाइल का क्या मतलब समझते हैं और आपका सिस्टम क्या स्वीकार करता है के बीच होता है। इसे रिलीज़ गेट मानिए।
एक व्यावहारिक टेस्ट: एक जानबूझकर गंदी फ़ाइल उपयोग करें। उदाहरण: एक CSV जहाँ हेडर दो बार प्रकट होता है (दो "email" कॉलम), एक boolean फ़ील्ड "Y" उपयोग कर रहा है, और एक तारीख "03/04/05" है। आपका इम्पोर्टर अनुमान नहीं लगाना चाहिए। या तो एक दस्तावेजीकृत मैपिंग लागू करें या विशिष्ट त्रुटि के साथ reject करें।
दो चेक जिन्हें टीमें अक्सर छोड़ देती हैं:
पहला, सत्यापित करें कि आपका इम्पोर्टर त्रुटियाँ इतनी लोकेशन डिटेल के साथ रिपोर्ट करता है कि स्रोत फ़ाइल ठीक की जा सके। "Invalid date" actionable नहीं है। "Row 42, column start_date: expected YYYY-MM-DD, got 03/04/05" है।
दूसरा, वही invalid फ़ाइल दो बार रन करें और परिणामों की तुलना करें। यदि त्रुटियों का क्रम बदलता है, कोड बदलते हैं, या रो नंबर्स drift करते हैं, तो यूज़र्स का भरोसा घट जाएगा। निर्धारक व्यवहार उबाऊ होता है, और वही उद्देश्य है।
एक सामान्य वास्तविक दुनिया इम्पोर्ट ग्राहक ऑर्डर है जो एक स्प्रेडशीट एक्सपोर्ट से आता है। कोई पुराना सिस्टम CSV एक्सपोर्ट करता है, Excel में एडिट होता है, फिर अपलोड होता है। अधिकांश टिकट तब होते हैं जब इम्पोर्टर मौन रूप से डेटा "सही" कर देता है, या जब त्रुटि संदेश यह नहीं बताता कि क्या बदलना है।
मान लीजिए फ़ाइल का नाम orders.csv है और कॉलम हैं: order_id,customer_email,order_date,currency,total_amount।
यहाँ तीन वास्तविक रूप से ख़राब रोज़ हैं (यूज़र की दृष्टि से):
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
रो 2 में invalid email और ambiguous date format है। रो 3 में order_id गायब है, unsupported currency code (US बजाय USD) है, और negative amount है।
यदि आपका API त्रुटियाँ लौटाता है, तो शेप सुसंगत और विशिष्ट रखें। एक हिस्सा‑सफलता को सपोर्ट करने वाला उदाहरण रिस्पॉन्स:
{
"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]
}
}
आंशिक सफलता मायने रखती है क्योंकि यूज़र्स को पूरी फ़ाइल फिर से अपलोड नहीं करनी चाहिए। एक सरल रीट्राई फ्लो: केवल फेल हुई रोज़ को ठीक करें, रो 2 और 3 वाली एक छोटी CSV एक्सपोर्ट करें, और री‑अपलोड करें। आपका इम्पोर्टर order_id मौजूद होने पर इसे आइडेम्पोटेंट मानकर उसी रिकॉर्ड्स को अपडेट करना चाहिए न कि डुप्लिकेट बनाना चाहिए।
सपोर्ट के लिए, correlation_id त्वरित निदान का सबसे तेज़ रास्ता है। सपोर्ट एजेंट वह एक वैल्यू पूछकर इम्पोर्ट रन लॉग में ढूँढ सकता है और पुष्टि कर सकता है कि पार्सर ने एक्स्ट्रा कॉलम देखे, गलत डेलिमीटर, या अनपेक्षित एन्कोडिंग।
दोहराने योग्य बनाने के अगले कदम:
अधिकांश विफलताएँ "कोड खराब है" की वजह से नहीं, बल्कि असल दुनिया के गंदे डेटा की वजह से आती हैं। CSV समस्याएँ आमतौर पर आकार/रचना से जुड़ी होती हैं (हेडर, डेलिमीटर, क्वोटिंग, एन्कोडिंग), जबकि JSON समस्याएँ अर्थ से जुड़ी होती हैं (टाइप, null बनाम empty, अनपेक्षित नेस्टिंग)। दोनों को अनट्रस्टेड इनपुट मानकर एक स्पष्ट कॉन्ट्रैक्ट के खिलाफ वैलिडेट करें।
तीन परिणाम पहले से परिभाषित करें:\n\n- Accepted: सब कुछ इम्पोर्ट हो गया।\n- Rejected: फ़ाइल पूरी तरह अस्वीकार्य है (गलत हेडर्स, पढ़ने योग्य नहीं JSON, खराब एन्कोडिंग)।\n- Partially accepted: मान्य रिकॉर्ड इम्पोर्ट होते हैं; अमान्य रिकॉर्ड स्किप किए जाते हैं और कारण स्पष्ट बताये जाते हैं।\n\nएक डिफ़ॉल्ट चुनें (कई उत्पाद partial चुनते हैं) और UI तथा API में इसका लगातार पालन करें।
इम्पोर्ट कॉन्ट्रैक्ट लिखने से पहले वैलिडेशन शुरू न करें:\n\n- स्वीकार्य फॉर्मेट (CSV डेलिमीटर, हेडर आवश्यक/अनिवार्य, UTF-8/BOM हैंडलिंग; JSON array vs object vs JSON Lines)\n- फ़ील्ड नियम (required/optional/defaults)\n- नॉर्मलाइज़ेशन (trim, case नियम, date formats)\n- डुप्लिकेट परिभाषा और हैंडलिंग\n- वैलिडेशन कहाँ होगी (क्लाइंट, सर्वर, या दोनों)\n\nयह लिखित कॉन्ट्रैक्ट "कल तक काम कर रहा था" वाली आश्चर्यजनक विफलताओं को रोकता है।
प्रत्येक फ़ील्ड के लिए एक अस्पष्ट एक ही फॉरमैट रखें (उदाहरण के लिए, date के लिए YYYY-MM-DD). यदि आप वैरिएंट स्वीकार करते हैं, तो इसे स्पष्ट और पूर्वानुमेय बनाइए (उदा. true/false/1/0 स्वीकार करें, पर हर स्प्रेडशीट अनुमान नहीं)। अस्पष्ट डेट्स जैसे 01/02/03 का अनुमान लगाने से बचें; या तो ISO फ़ॉर्मेट माँगें या स्पष्ट त्रुटि लौटाएँ।
निर्णय लें:\n\n- क्या गिनें डुप्लिकेट के रूप में (email, external_id, या कम्पोजिट)\n- पता लगाने की सीमा (फ़ाइल के भीतर, मौजूदा रिकॉर्ड्स के खिलाफ, या दोनों)\n- किस कार्यवाही से निपटा जाए (first रखें, last रखें, merge करें, या reject करें)\n\nयदि यूज़र retry कर सकते हैं, तो idempotency के साथ संयोजन करें ताकि एक ही अपलोड डुप्लिकेट न बनाए।
एक लेयरड तरीका अपनाएँ बजाय एक विशाल validate() फ़ंक्शन के:\n\n- Normalize: कच्चे इनपुट को canonical आकार में बदलें\n- Field-level rules: छोटे, पुन:उपयोगी चेक (type, range, enum)\n- Cross-field rules: स्पष्ट लक्ष्यों के साथ संबंध-आधारित चेक\n- File-level rules: required headers, duplicate keys, supported version\n\nछोटे नामित नियम बदलने और परीक्षण लिखने में आसान होते हैं।
स्थिर त्रुटि आकार लौटाएँ:\n\n- code (स्थिर पहचानकर्ता)\n- message (यूज़र‑फ्रेंडली)\n- / (कॉलम नाम या JSON pointer)\n- / (CSV के लिए)\n- ( vs )\n\nजब संभव हो तो अपेक्षित और वास्तविक मान दिखाएँ। भाषा-तटस्थ रखें ताकि बाद में संदेश बदलें पर क्लाइंट फ़िल्टर और एनालिटिक्स काम करते रहें।
हमेशा एक सुसंगत सारांश लौटाएँ, भले ही त्रुटियाँ हों:\n\n- काउंट्स: created, , , , साथ में \n- (success, rejected, completed_with_errors)\n- timestamps (, )\n- एक सपोर्ट/डिबगिंग के लिए\n\nबड़ी फ़ाइलों के लिए एक छोटा और पूरा रिपोर्ट फ़ेच करने का तरीका दें।
रिट्राई का समर्थन स्पष्ट रूप से करें:\n\n- एक idempotencyKey स्वीकार करें (या फ़ाइल हैश का उपयोग करें)\n- यदि वही रिक्वेस्ट दोहराई गई है तो मौजूदा importId लौटाएँ\n- upsert मैचिंग नियम परिभाषित करें (उदा. email यूनिक की)\n\nइसके बिना, सामान्य यूज़र रिट्राई से रिकॉर्ड डबल‑क्रिएट हो सकते हैं।
कुछ ज्ञात‑अच्छे सीड फाइलों से शुरू करें, फिर छोटे म्यूटेशन जनरेट करें (एक बार में एक बदलाव):\n\n- एन्कोडिंग (UTF-8 BOM, invalid bytes)\n- संरचना (मिसिंग हेडर्स, एक्स्ट्रा कॉलम, गलत डेलिमीटर)\n- क्वोटिंग/न्यूलाइन (अनक्लोज्ड कोट्स, एम्बेडेड न्यूलाइन)\n- टाइप एजेस (बहुत बड़े नंबर, empty vs null, NaN/Infinity JSON)\n- साइज लिमिट्स (बहुत लंबा फील्ड, गहरी नेस्टिंग)\n\nपास का मतलब: कोई क्रैश/हैंग नहीं, डीटर्मिनिस्टिक त्रुटियाँ, और एक्शन योग्य त्रुटि रिपोर्ट्स।
pathfieldrowlineseverityerrorwarningcodeupdatedskippedfailedtotalRows/totalRecordsstatusstartedAtfinishedAtcorrelationIderrorsSample