فشل استدعاء الـ API للتو مع JSONDecodeError: Expecting property name enclosed in double quotes. الوقت يدق. البيانات قادمة من LLM، وفي مكانٍ ما داخل ذلك الرد المكوّن من 2000 رمز، فاصلة زائدة واحدة ألحقت كامل خط المعالجة لديك.
حتى مايو 2026، أسرع طريقة لـ إصلاح ملفات JSON التالفة هي استخدام مكتبات آلية مثل json_repair (لـ Python) أو jsonrepair (لـ npm). صُمّمت هذه الأدوات خصيصًا لإصلاح أخطاء الصياغة الناتجة عن LLM فورًا. أما الإصلاحات اليدوية، فالمتهمون المعتادون هم الفواصل الزائدة، أو علامات الاقتباس المفردة، أو المفاتيح غير المقتبة — وهي أكثر ثلاثة انتهاكات شيوعًا لمعيار RFC 8259.
الإصلاح الأسرع: json_repair لمخرجات LLM
المحلّلات القياسية مثل json.loads() في Python صارمة بالتصميم. حرفٌ واحد في غير موضعه يطلق JSONDecodeError ويتوقف كل شيء. هذه مشكلة يومية في عام 2026 لأن نماذج LLM غالبًا ما تلفّ JSON داخل نصٍّ حواري، أو تقطع الاستجابة في منتصف الجملة، أو تنثر تعليقات تكسر المواصفات.
مكتبة json_repair هي الحل المفضل. وفقًا لـ GitHub، حصد هذا المشروع أكثر من 4700 نجمة حتى عام 2026. تعمل عبر “تخمين” نيّة السلسلة النصية — إغلاق الأقواس المفقودة، وإضافة علامات الاقتباس، وإزالة النصوص الزائدة حول كتلة JSON.
Python: قبل وبعد
التثبيت: pip install json-repair
الإدخال التالف:
import json_repair
bad_json = '{"user": "Alice", "status": tru'
decoded_object = json_repair.loads(bad_json)
ماذا حدث خلف الكواليس: أدرك json_repair أن tru كانت على الأرجح true، وأضاف القوس المغلق المفقود، وأرجع قاموسًا صالحًا في Python. تدخّل يدوي صفري.
وضع الإنقاذ: عندما تكون البيانات سيئة حقًّا
للحالات الأصعب، تتضمّن json_repair (الإصدار v0.59.5+) Salvage Mode (وضع الإنقاذ). كما هو موضّح في وثائق المشروع، بُني هذا الوضع تحديدًا للاستجابات المقطوعة للذكاء الاصطناعي أو السجلات التالفة. يمكنه تحويل المصفوفات قسرًا إلى كائنات أو حذف العناصر التي يستحيل إنقاذها، مما يضمن ملاءمة المخرجات لمخطّطك.
import json_repair
# Salvage mode for severely truncated data
result = json_repair.loads(
'{"items": [{"id": 1, "name": "Widget"}, {"id": 2, "na',
salvage_mode=True
)
# Result: {'items': [{'id': 1, 'name': 'Widget'}, {'id': 2}]}
# Dropped the incomplete 'na' but saved everything else
بديل npm
لمشاريع Node.js، تقوم أداة jsonrepair CLI بنفس المهمة:
# Fix a file in place
npx jsonrepair broken.json > fixed.json
# Fix a string in a script
const { jsonrepair } = require('jsonrepair');
const fixed = jsonrepair('{"name": "test",}');
التصحيح اليدوي: العثور على ما كسر المواصفات
عندما لا تكفي الأتمتة، عليك تحديد الموضع الذي ينتهك فيه الملف RFC 8259 بدقة. JSON أقل تساهلًا بكثير من YAML أو JavaScript. كما يشرح فريق تشخيص JSONParser: “يفشل المحلّل عند أول حرف لا يستطيع فهمه، وهو غالبًا عرضٌ ناتج لمشكلة تقع قبل ذلك بأسطر.”
قتلة JSON الثلاثة
القاتل 1: الفواصل الزائدة
وفقًا لـ DEV Community، الفواصل الزائدة هي السبب الأول لفشل التحليل. لا بأس بها في JavaScript لكنها غير قانونية بعد العنصر الأخير في مصفوفة أو كائن JSON.
// BROKEN - trailing comma after "active"
{
"name": "Alice",
"status": "active",
}
// FIXED - no comma before closing brace
{
"name": "Alice",
"status": "active"
}
القاتل 2: علامات الاقتباس المفردة
يتطلّب JSON علامات اقتباس مزدوجة (") لكلٍّ من المفاتيح وقيم السلاسل النصية. كثير من مطوّري Python و JavaScript يستخدمون عن طريق الخطأ علامات اقتباس مفردة ('). كما يلخّص TidyCode، هذا تصحيح إلزامي.
// BROKEN - single quotes
{'name': 'Alice'}
// FIXED - double quotes
{"name": "Alice"}
القاتل 3: المفاتيح غير المقتبة
في JavaScript يمكنك كتابة { name: "Alice" }. أما في JSON، فكل مفتاح يحتاج إلى علامتي اقتباس مزدوجتين.
// BROKEN - unquoted key
{name: "Alice"}
// FIXED - quoted key
{"name": "Alice"}
خطأ “Unexpected Token”
عندما يُبلغ مدقّق عن “Unexpected Token”، فهذا يعني أن المحلّل صادف NaN أو Infinity أو undefined — وهي ثوابت JavaScript لا يدعمها JSON. يسمح JSON فقط بـ null و true و false والأرقام.
// BROKEN - NaN is not valid JSON
{"score": NaN, "result": Infinity}
// FIXED - replace with null or valid values
{"score": null, "result": null}
التحليل الصارم مقابل تحليل الإصلاح: متى تستخدم كلًّا منهما
النهج الصحيح يعتمد على مصدر بياناتك. ملفات الإعداد التي يحرّرها البشر تستحق تحليلًا صارمًا لإجبار الكاتب على إصلاح أخطائه. أمّا البيانات المولّدة آليًا من LLM أو سجلات API فتحتاج تحليلًا قائمًا على الإصلاح.
| الميزة |
صارم (json.loads) |
إصلاح (json_repair) |
| الفواصل الزائدة |
يطلق JSONDecodeError |
تُزال تلقائيًا |
| علامات الاقتباس المفردة |
يفشل |
تُحوَّل إلى علامات مزدوجة |
| البيانات المقطوعة |
يفشل |
يُغلق الأقواس/الاقتباسات المفتوحة |
| التعليقات |
يفشل |
تُزال تلقائيًا |
| أفضل حالة استخدام |
ملفات إعداد يحرّرها البشر |
مخرجات LLM، سجلات API |
إصلاحات موجَّهة بالمخطّط باستخدام Pydantic
يمكنك توجيه عملية الإصلاح باستخدام Pydantic v2 أو JSON Schema. بإعطاء json_repair مخطّطًا، تقوم الأداة بأكثر من مجرد إصلاح الصياغة — يمكنها تصحيح الأنواع (تحويل السلسلة "1" إلى الرقم 1) وملء الحقول المطلوبة المفقودة بقيم افتراضية.
from pydantic import BaseModel
import json_repair
class User(BaseModel):
id: int
name: str
active: bool = True
# Broken JSON with wrong types
raw = '{"id": "42", "name": "Alice"}'
repaired = json_repair.loads(raw)
# Validate against schema
user = User(**repaired)
# user.id is now int(42), user.active defaults to True
كما أشار Stefano Baccianella في إسناده للمشروع عام 2025، تم تحسين هذا النهج لـ JSON “الصحيح في معظمه لكنه غير صالح تقنيًا” والذي تميل نماذج اللغة إلى إنتاجه.
التعامل مع ملفات بحجم غيغابايت دون انهيار
إصلاح مقطع بحجم 10KB أمر سهل. أمّا إصلاح ملف بحجم 2GB فيتطلّب استراتيجية لن تستهلك ذاكرتك كلها. تحميل الملف بأكمله في الذاكرة يسبّب أخطاء نفاد الذاكرة (OOM).
الاستراتيجية 1: البثّ باستخدام ijson
للبيانات الضخمة، استخدم ijson لمعالجة البيانات قطعة بقطعة. كما يذكر Scrapfly، يعالج ijson البيانات بشكل تزايدي. اقرنه بنص برمجي للتنظيف يصلح المشاكل سطرًا بسطر قبل التحليل.
import ijson
# Stream through a large JSON file
with open('huge_broken.json', 'r') as f:
for item in ijson.items(f, 'records.item'):
# Process each item individually
process(item)
الاستراتيجية 2: أنبوب CLI لأقصى كفاءة
النهج الأوفر للذاكرة مع الملفات الكبيرة هو استخدام jsonrepair CLI وتوجيه المخرجات مباشرةً إلى ملف جديد:
# Streams repair, never loads full file into memory
jsonrepair large_broken.json > fixed.json
هذا أوفر للذاكرة بكثير من تحميل الملف إلى Python أو متصفّح.
الخاتمة
إصلاح JSON التالف لم يعد مهمة يدوية بفضل المكتبات المدركة للذكاء الاصطناعي مثل json_repair. ما زلت بحاجة لفهم أساسيات RFC 8259 — لا فواصل زائدة، ولا علامات اقتباس مفردة، ولا مفاتيح غير مقتبة — لكن الأتمتة هي النهج العملي الوحيد مع البيانات في حجم عام 2026.
سير العمل بسيط: جرّب مكتبة إصلاح أولًا. إن فشلت، استخدم مدقّقًا لتحديد خطأ الصياغة بالضبط. هذا يبقي تطبيقاتك قيد التشغيل حتى حين تكون البيانات الواردة أقل من الكمال.
الأسئلة الشائعة
هل يدعم JSON رسميًا التعليقات أو علامات الاقتباس المفردة؟
لا. يمنع معيار RFC 8259 التعليقات بصرامة. علامات الاقتباس المفردة غير صالحة أيضًا — يُسمح فقط بعلامات الاقتباس المزدوجة للمفاتيح والسلاسل النصية. ومع ذلك، يمكن لأدوات مثل json_repair إزالة التعليقات وتحويل علامات الاقتباس تلقائيًا لجعل الملفات قابلة للتحليل بالمكتبات القياسية.
كيف أتعامل مع ملفات JSON تالفة وكبيرة جدًّا دون انهيار؟
استخدم محلّلًا تدفقيًا مثل ijson لمعالجة البيانات في أجزاء. تجنّب تحميل السلسلة التالفة بأكملها في متغيّر واحد. للحصول على أسرع النتائج، استخدم أدوات إصلاح CLI التي توجّه المخرجات مباشرةً إلى ملف جديد على القرص دون الاحتفاظ بكل شيء في الذاكرة.
ما الفرق بين JSON التالف و JSON غير الصالح؟
JSON التالف ينتهك قواعد الصياغة — أقواس مفقودة، مفاتيح غير مقتبة، فواصل زائدة — مما يجعل تحليله مستحيلًا. أما JSON غير الصالح فيتبع كل قواعد الصياغة لكنه يفشل في مطابقة JSON Schema محدّد (مثلًا، حقل نصي بينما يتوقّع المخطّط عددًا صحيحًا). إصلاح JSON التالف هو إصلاح بنيوي؛ وإصلاح JSON غير الصالح يتعلّق بسلامة البيانات.
هل يمكنني استخدام json_repair مع التحقق من Pydantic؟
نعم. شغّل json_repair.loads() أولًا لإصلاح أخطاء الصياغة، ثم مرّر القاموس المُصلَح إلى نموذج Pydantic للتحقق من الأنواع وفرض المخطّط. هذا النهج من خطوتين يعالج كلًّا من المشاكل البنيوية والمعنوية.
ماذا عن JSON مع تعليقات بأسلوب JavaScript؟
JSON القياسي لا يدعم التعليقات، لكن json_repair يمكنه إزالة تعليقات // و /* */ تلقائيًا. إن كنت تحتاج تعليقات في ملفات الإعداد، فكّر في استخدام صيغة JSONC (JSON مع تعليقات) ومحلّل متوافق مثل json5 لـ Python.
