# مفتاح إعداد مكرر يختفي قبل التحقق: ارفض الأسماء المكررة في JSON

> **الرابط:** https://aiseza.com/566/python-json-duplicate-preset-keys-object-pairs-hook/
> **الكاتب:** INESSE MOUSBIR
> **النشر:** 2026-11-06
> **آخر تحديث:** 2026-11-06

## الإجابة المختصرة

في النص التجريبي تتكرر seed بقيمتين. يحتفظ التحليل المعتاد بالقيمة 11، بينما يتيح object_pairs_hook رفض التكرار قبل تكوين القاموس.

في ملف إعدادات تجريبي لمشهد، تبدأ القيمة الأولى للمفتاح `seed` بالعدد 7. يظهر المفتاح نفسه بعد ذلك بقيمة 11. اقرأ النص كما هو، ثم اطلب من `json.loads` تحويله إلى قاموس. في التجربة المحلية خرج قاموس فيه `seed` مرة واحدة وقيمته 11. إذا وصل هذا القاموس إلى دالة تتحقق من أن القيمة عدد صحيح، فقد ينجح الفحص ولا ترى الدالة القيمة 7 قط. لذلك نحتاج أن نطرح سؤال التكرار قبل السؤال عن نوع القيمة.

أعد المثال إنتاج النتيجة بنص صغير لا يتصل بأي خدمة. وعند تمرير النص نفسه إلى `load_preset` حصلنا على `DuplicateKeyError`. المفتاح في التجربة جزء من وصف مشروع افتراضي. لم يستدع البرنامج نموذج صور ولم يقارن النتائج الناتجة عن البذرتين. ما نريد حفظه هو الفرق بين ملاحظة مباشرة عن محلل بايثون وقرار يتخذه صاحب المشروع عندما يجد قيمتين في مصدر واحد.

## اعزل القيمة التي لم تعد موجودة في القاموس

ابدأ من نسخة من النص الذي قرأه التطبيق. في المثال المحفوظ يبدو الإدخال هكذا في سطر واحد، `{"seed":7,"seed":11}`. تنتمي القيمتان إلى الكائن نفسه. وجود علامتي الاقتباس حول الاسمين والفاصلة بين الزوجين يسمح للمحلل بالتعرف على الزوجين في المصدر. لكنه ينشئ تمثيلاً له مدخل واحد لكل اسم في القاموس. بعد انتهاء التحليل الافتراضي، تصبح القيمة 11 هي التي تستطيع قراءتها من المفتاح. لا يمكن استنتاج القيمة 7 من القاموس الناتج وحده.

هذه الخطوة مفيدة عند البحث عن إعداد تغيّر بين نسختين من المشروع. إذا كنت تفتح الملف في أداة تعرضه في شجرة خصائص، تحقق مما إذا كانت الأداة تعرض النص أو نتيجة التحليل. قد تُظهر الشجرة مفتاحاً واحداً كما يفعل القاموس. افتح نسخة النص الأصلية في محرر عادي إذا احتجت أن ترى الموضعين. احفظها قبل إعادة تنسيقها بواسطة أداة تقرأها وتكتبها من جديد. إعادة الكتابة من تمثيل لا يحمل إلا القيمة الأخيرة قد تزيل الدليل الذي تريد مراجعته.

في المثال تُستخدم كلمة `seed` لسهولة ملاحظة الفرق بين عددين صالحين من حيث النوع. يمكن أن يحدث الأمر نفسه مع مسار ملف أو حجم صورة أو خيار تشغيل. قد يمر العدد 11 من فحص النطاق بينما يمر العدد 7 أيضاً. قبول القيمة الثانية وفق القواعد لا يحل خلافاً بين المصدرين اللذين كتبا المفتاح. أحياناً يقصد محرر الملف تحديث القيمة الأولى. وأحياناً تكون الثانية جزءاً من قالب أضيف دون مراجعة. رسالة خطأ صريحة تحفظ فرصة اتخاذ القرار على أساس سجل التعديل.

فرّق بين ما قدّمه اختبارنا وبين توافق الأنظمة الأخرى. النتيجة 11 تخص التحليل الافتراضي الذي شُغّل في بايثون في هذه التجربة. إذا انتقل الملف إلى قارئ آخر، راجع سلوكه الفعلي قبل أن تجعل اختيار آخر قيمة جزءاً من عقد المشروع. يمكن أن تتفق تطبيقاتك على رفض الملف المتكرر قبل إرساله إلى أي جهة. بذلك يصبح لكل إعداد مصدر يمكن تفسيره من دون الاعتماد على ترتيب السطور.

## راقب أزواج الكائن قبل تكوين التمثيل النهائي

في `load_preset` نمرر `unique_pairs` إلى معامل `object_pairs_hook` عند استدعاء `json.loads`. يستقبل الخطاف قائمة أزواج الكائن الذي يجري بناؤه. تكون الأسماء قد قُرئت من صيغة JSON. تحافظ القائمة على وجود الزوجين حتى عندما يتساوى الاسمان بعد فك الترميز. هذا هو الموضع الذي يسمح بفحص كل اسم قبل إدخاله في قاموس النتيجة.

يحتفظ محلل json افتراضياً بالقيمة الأخيرة عند تكرار الاسم، ويمكن تمرير object_pairs_hook لاستقبال أزواج كل كائن. [Python 3.12 json reference](https://docs.python.org/3.12/library/json.html)

تبدأ `unique_pairs` بقاموس فارغ جديد. تمر على كل زوج بالترتيب. إذا لم يكن الاسم موجوداً، تضيفه مع قيمته. عند وصول اسم موجود بالفعل، ترفع `DuplicateKeyError` وتستعمل `repr(key)` في نص الرسالة. التحقق يتعلق بوجود المفتاح نفسه. لا يختبر صدق القيمة، ولا يقرر أن التطابق مقبول عندما تتساوى القيمتان. حتى إذا أراد الكاتب تكرار القيمة نفسها، يبقى الاسم الثاني تكراراً وفق السياسة التي تطبقها هذه الدالة.

تصوّر فحصاً يعتمد على القيمة المسترجعة من القاموس بدلاً من العضوية فيه. إذا كان المفتاح الأول يحمل 0 أو `false` أو قيمة فارغة، فقد يكون من السهل على شرط غير دقيق أن يتعامل معه كأنه غائب. لهذا يقرأ المثال الشرط `key in result`. فوجود القيمة وكونها مقبولة أو قابلة للتحويل أمران منفصلان. لا تحتاج دالة اكتشاف التكرار إلى تفسير المعنى الذي يحمله الرقم أو النص.

عند وصول الخطأ لا تعيد الدالة قاموساً جزئياً إلى المستدعي. يمكن للمستدعي أن يربط إيقاف القراءة بمسار الملف الذي يعرفه أصلاً. يمكنه بعد ذلك عرض الخطأ أو رفض عملية حفظ تعتمد على هذا المصدر. لا تضيف الشيفرة الحالية اسم الملف أو رقم السطر أو مسار الكائن المتداخل إلى الاستثناء. الخطاف يتلقى أزواج الكائن، وهي المعلومة التي تحتاجها سياسة التكرار. إذا احتجت إلى تمييز الموضعين في محرر إعدادات، فاختبر أداة تحفظ مواضع الرموز من النص أو صمم طبقة تشخيص تتلقى هذه المعلومات من محلل مناسب.

بعد نجاح التحليل، تتحقق `load_preset` من أن الجذر قاموس. ثم يمكن للتطبيق أن يسأل عن الحقول المطلوبة وأنواعها ونطاقها. يأتي [التحقق من بنية JSON قبل التخزين](https://aiseza.com/448/validate-ai-json-before-storage/) بعد نجاح التحليل. إذا كان الاسم قد اختفى أثناء تكوين القاموس، فلن يكشف فحص البنية وحده أن المصدر كتبه مرتين.

## حدد أين يبدأ نطاق الاسم وأين ينتهي

يعني التكرار في هذه السياسة تطابق اسمين داخل كائن واحد. قد تحتوي إعدادات مشروع على كائن للكاميرا وآخر للإضاءة. يمكن لكل منهما استخدام اسم مثل `x` بمعنى تحدده البنية. يبدأ الخطاف بقاموس جديد لكل كائن، فتظل الأسماء داخل الكاميرا مستقلة عن الأسماء في الإضاءة. لو خزنّا كل الأسماء في مجموعة واحدة تخص الملف كله، لأصبح ظهور `x` في الكائن الثاني خطأ مع أنه جزء صحيح من وصف المشروع.

في الاختبار المحلي المسمى `test_nested_duplicate_rejected` يوجد `x` بقيمتين داخل كائن `camera`. يتوقف التحليل عند رفض هذا الكائن. وفي `test_same_key_in_distinct_objects_allowed` يظهر `x` في كل من `a` و`b`. ينجح التحليل ويقرأ الاختبار العدد 2 من `b`. ويمكن أن تقع الكائنات نفسها داخل مصفوفة. يضع اختبار آخر كائناً ذا اسم مكرر ضمن `items`، ويتأكد من وصول خطأ التكرار. المصفوفة تجمع عناصر مرتبة. كل كائن داخلها يملك قائمة أزواج تخصه.

تفيد هذه الحدود عند كتابة قوالب مشاريع لها بدائل. افترض وجود مصفوفة لمشهدين، لكل واحد اسم وخلفية وبذرة. وجود مفتاح `seed` في المشهد الأول وفي الثاني أمر متوقع. أما ظهور المفتاح مرتين في كائن المشهد الأول فيمنع فهم الطلب الخاص به. وإذا احتاج المشروع إلى فرض تفرّد قيم البذور نفسها بين المشاهد، فذلك شرط على القيم بعد التحليل. فحص أسماء المفاتيح لا يرى في تساوي عددين عبر كائنين مخالفة.

الاسم الذي تقارنه الدالة هو السلسلة الناتجة بعد قراءة JSON. يستطيع النص مثلاً أن يكتب الحرف `e` مباشرة أو يمثله بتسلسل Unicode. عند قراءة `"se\u0065d"` ينتج الاسم `seed`. عندما يأتي بعده `"seed"` في الكائن نفسه، يقارن الخطاف سلسلتين متساويتين. الاختبار الحالي يمرر الشرطة المائلة إلى محلل JSON باستخدام سلسلة Python خام. في النسخة السابقة كانت Python تفسر التسلسل أولاً، فكان الاختبار يعيد فحص اسمين حرفيين متساويين. حفظنا النسخة السابقة وصححنا الإدخال ثم أعدنا تشغيل المجموعة كاملة.

تعامل السياسة الحالية `Seed` و`seed` كاسمين مختلفين. احتوى الاختبار على الاثنين معاً، وقارن القاموس الناتج بالقيمتين 7 و11. لا تستخدم الدالة طي حالة الحروف، ولا توحيد الأسماء وفق أشكال Unicode، ولا حذف المسافات منها. إذا كان مشروعك يعد اسمين متشابهين وفق قواعد إضافية شيئاً واحداً، اختر موضعاً واضحاً لهذه القاعدة واختبرها بأسماء متوقعة فعلاً. تغيير المساواة في قارئ إعدادات قائم قد يجعل ملفات كانت تُقرأ سابقاً ترفض في النسخة التالية.

### unique_json.py

```
import json

class DuplicateKeyError(ValueError):pass

def unique_pairs(pairs):
    result={}
    for key,value in pairs:
        if key in result:raise DuplicateKeyError('Duplicate key: '+repr(key))
        result[key]=value
    return result

def load_preset(text):
    result=json.loads(text,object_pairs_hook=unique_pairs)
    if not isinstance(result,dict):raise ValueError('Preset root must be an object')
    return result
```

نطاق التحقق المحلي: 11 local Python JSON tests, including a raw JSON string containing a literal Unicode escape. Identical decoded keys are rejected within each object. The fixture does not verify schema, numeric rules or model behavior.؛ البيئة: Python 3.12.3 on Windows

## اربط كل نتيجة باختبار يمكن قراءته

تحتوي المجموعة على 11 اختباراً شُغّلت محلياً في Python 3.12.3. الاختبار الأول للنتيجة الافتراضية يقارن قاموس `json.loads` بالقيمة 11. الاختبار التالي يقرأ النص نفسه عبر `load_preset` وينتظر `DuplicateKeyError`. وجود المقارنة في اختبارين يسمح لك بتحديد الفرق الذي أحدثته السياسة. اختبار الرفض وحده لا يسجل ماذا كان يحدث عند قراءة الملف بالطريقة السابقة.

الأسماء المتداخلة لها اختبارات مستقلة حتى يظهر موضع الاختلاف عند تعديل المثال. الكائن الفرعي المتكرر يُرفض. الكائن الموجود داخل مصفوفة يُرفض عندما يتكرر الاسم داخله. ووجود الاسم في كائنين منفصلين ينجح. راقب ما يؤكده كل اختبار. اختبار قبول الكائنين يقرأ قيمة محددة من `b`، لذلك يفيد في تأكيد بقاء هذا الفرع وقيمته. إذا أردت ضمان ظهور جميع الحقول في مشروع أوسع، فقارن التمثيل الكامل في مثال آخر يناسب ذلك العقد.

هناك اختبار يقرأ مفتاحاً عربياً سليماً ويربط `مشهد` بالنص `إبريق`. يبين ذلك أن الفحص يمرر هذا الاسم وهذه القيمة كما في القاموس المتوقع. وهو لا يختبر كيفية عرضهما في محرر بعينه، ولا يغطي كل أنواع التطبيع أو تسلسلات Unicode. حالة التسلسل المهرب تُختبر بمفتاح مختلف لكي نعرف بالضبط أين يُفك الترميز. عندما تعدل الحالات، أبق الاختبار المخصص للتسلسل منفصلاً عن اختبار الاسم العربي حتى تظل الرسالة واضحة إذا تعطل أحدهما.

يمكنك إعادة تشغيل المجموعة في مجلد المثال الذي يضم `unique_json.py` و`test_example.py` عبر اكتشاف اختبارات `unittest`. تستخدم الحالات نصوصاً ثابتة، لذلك لا تحتاج إلى ملف إعدادات من تطبيقك. احتفظ بنسخة الاختبار التي شغلتها وبناتجها عند مقارنة بيئة أخرى. إذا كنت تعيد إنتاج بلاغ يتعلق بنص طويل، اختصره إلى أصغر كائن يبقي التكرار في موضعه. من المفيد إبقاء الأسماء في فرعين منفصلين في حالة النجاح المقابلة لتوضيح أن المطلوب هو تكرار الاسم داخل كائن بعينه.

في تطبيق عملي قد ترغب في اختبار مسار القراءة كاملاً بعد نجاح هذه المجموعة. مرّر ملفاً مملوكاً للتجربة إلى نقطة الدخول التي يستخدمها التطبيق، ثم راقب أنها تستعمل القارئ نفسه. قد تكون دالة `load_preset` صحيحة بينما يستمر أمر قديم في استدعاء `json.loads` مباشرة. ضع نصاً يحوي تكراراً في هذا المسار ثم تحقق من أن التطبيق يتوقف قبل قبول الإعداد. هذا اقتراح لاختبار الربط، بينما الاختبارات المحفوظة هنا تستدعي وظائف المثال مباشرة.

## أعط أخطاء النص والجذر والتكرار أسماء واضحة

يحافظ المثال على خطأ الصياغة الذي يرفعه المحلل عندما يقرأ النص `{` وحده. هذه حالة الاختبار الذي ينتظر `json.JSONDecodeError`. في هذا الإدخال لم يكتمل بناء الكائن. عندما ترى خطأ صياغة، افحص موضعه وفق ما أبلغ به المحلل. وفي الملف الذي يحوي اسمين متساويين قد تكون الصياغة مقروءة، لكن سياسة إعدادات المشروع ترفض تكوين القاموس. نوع الخطأ يساعد المستدعي على تحديد أي إصلاح يناسب الحالة.

يختبر المثال أيضاً المصفوفة الفارغة `[]`. يستطيع `json.loads` قراءتها، لكن `load_preset` تشترط قاموساً في الجذر فترفع `ValueError`. ينجح الكائن الفارغ `{}` في هذه الدالة. الفارق مهم عند تعريف معنى الملف الصحيح. شرط الجذر يميز كائناً من مصفوفة، لكنه لا يثبت وجود حقل مطلوب مثل `seed`. إذا كان هذا الحقل إلزامياً، ضع فحصه بعد القراءة في طبقة تختص بإعدادات مشروعك.

عندما تكتب معالج الأخطاء، انتبه إلى أن `DuplicateKeyError` مشتق من `ValueError` في المثال. ويستخدم محلل Python أيضاً استثناءً مشتقاً من `ValueError` لأخطاء فك JSON. إذا التقطت الفئة العامة أولاً، قد تعرض الرسالة نفسها لتكرار مفتاح ونص ناقص وجذر غير مناسب. يمكنك التقاط الفئات الأكثر تحديداً قبل الفئة العامة إذا أردت أن تشير كل رسالة إلى الخطوة التي فشلت. اختبر الرسائل من خلال نقطة الدخول الفعلية إذا كانت واجهة التشغيل تعتمد عليها.

هذه الدالة تحدد عقداً ضيقاً. إنها تستعمل قواعد التحليل الافتراضية للأرقام، مع إضافة فحص الأسماء وشرط الجذر. لم نغيّر تعامل المكتبة مع قيم مثل `NaN` أو `Infinity`، ولم نضع حداً لحجم الإدخال أو عمقه في الشيفرة المعروضة. إذا كان ملفك ينتقل إلى نظام يفرض قواعد أخرى، حدّدها على حدة واستخدم حالات تعبر عن تلك القواعد. إضافة اعتراض للأزواج لا تعفي التطبيق من تعريف نطاق القيم التي يقبلها ومن فحص ما يعتمد عليه عند العمل.

## صحح المكان الذي كتب المفتاح مرتين

عند ظهور الخطأ في ملف إعدادات حقيقي، احتفظ أولاً بالنص الذي رُفض وأثر التعديل الذي أنشأه إذا كان متاحاً. اقرأ الموضعين داخل الكائن نفسه وقارن القيمتين مع القرار الذي أراد صاحب الإعداد تطبيقه. في مشروع يدمج ملفاً أساسياً مع إعداد خاص بمشهد، افحص ما إذا كان الكاتب يلصق قطعتين نصيتين داخل الأقواس نفسها. إذا كان التجاوز مقصوداً، اجعله عملية دمج صريحة بين تمثيلين معروفين. اكتب الناتج بعد أن يتحدد مصدر كل قيمة وفق قاعدة يفهمها الفريق.

في حالة البذرتين 7 و11 يمكن لإصلاح المصدر أن يبقي أياً منهما بعد معرفة سبب وجودهما. الشيفرة لا تختار الرقم الأفضل. إذا كان المطلوب الاحتفاظ بكلتا المحاولتين، غيّر البنية بحيث يظهر كل إعداد في كائنه ضمن مجموعة محاولات. بذلك تستطيع قراءة الاسم نفسه في نطاقين وتسجيل المعرف الذي يربط كل محاولة بمخرجاتها. هذا قرار في تصميم الملف. لا تحتاج إلى قبول مفاتيح مكررة كي تحفظ أكثر من قيمة ذات معنى.

إذا كنت تحول مشروعاً موجوداً إلى سياسة الرفض، جرّب القراءة على نسخ من ملفات مختارة قبل تغيير المسار الذي يطلق المهام. سجل الملف الذي فشل واسم المفتاح الذي أبلغه الاستثناء. اطلب من مالك الإعداد تفسير الحالات التي لا يمكن حسمها من السياق. ثم شغّل الفحص على النص المصحح، وافحص الحقول المطلوبة في الخطوة التالية. وجود قائمة بالملفات التي تحتاج قراراً قد يكون أكثر عملية من إعادة كتابة كل ملف تلقائياً وفق اختيار آخر قيمة.

يمكن وضع القارئ في مكان واحد يستعمله أمر المعاينة وأمر تجهيز الدفعة. ويمكن لأداة فحص محلية أن تقرأ ملفات محددة قبل حفظ تغيير مشترك. حتى تكون هذه الخطوة نافعة، مرر النص الأصلي إليها قبل أي أداة تعيد تنسيقه. ثم اختبر حالة مقبولة وحالة مرفوضة عبر الأمر نفسه. إذا كنت تجمع ملفات من مدخلات متعددة، ابدأ ببيان حدود هذه الأداة، وما الذي يعرفه المستدعي عن الملف، وما الذي يوفره الاستثناء عن الاسم.

عندما يتكرر البلاغ في وقت لاحق، حاول أن تحصل على ثلاث قطع من الأدلة في سجل التطوير. احتفظ بمقتطف صغير من النص يحفظ موضعي الاسم، وبنتيجة القارئ الذي استُخدم، وبالقرار الذي أصلح المصدر. يمكن عندئذ أن يرى المراجع هل بقي الاسم مكرراً داخل الكائن نفسه أم ظهر في كائنين منفصلين. وقد يكتشف أن الاختلاف في الترميز يقع قبل قراءة الملف أو أن القارئ لم يمر عبر الدالة التي فحصناها. هذه التفاصيل تتيح إعادة إنتاج السؤال الذي واجهه المشروع قبل تعديل إعداد له آثار لاحقة.

## حدد موضع القراءة في مشروع يجمع أكثر من ملف

افترض مشروعاً يملك ملفاً عاماً للأبعاد والإضاءة وملفاً صغيراً لإعدادات كل مشهد. يحتوي الملف العام على `seed` بقيمة 7، وتختار إعدادات أحد المشاهد القيمة 11. اقرأ كل ملف بصفته نصاً مستقلاً. إذا كان كل منهما يحتوي على مفتاح واحد، يقبل القارئ الملفين. ثم يختار المشروع سياسة دمج واضحة تجعل القيمة الأقرب إلى المشهد هي التي تحكمه. الفارق عن المثال المرفوض هو أن التعارض هنا وقع بين مصدرين معروفين ويمكن تفسيره. في المثال المرفوض وقع الاسمان داخل كائن واحد وتحتاج إلى قرار قبل أن تعتمد أحدهما.

إذا كتب البرنامج الناتج النهائي إلى ملف جديد، فقد ترى في الملف الناتج `seed` مرة واحدة مع القيمة 11. لا يكفي ذلك لإثبات أن كل مدخل كان سليماً. ربما قرأ أحد المكونات الملف العام بقارئ يختار آخر قيمة ثم مرر قاموسه إلى المكوّن الذي يدمج الإعدادات. لذلك يفيد وضع شرط القراءة عند كل نقطة تدخل منها وثيقة JSON إلى عملية الدمج. تستطيع في اختبار تكامل أن تضع المفتاح مرتين داخل الملف العام، ومرة داخل الملف الخاص. النتيجة التي تريدها هي توقف القراءة قبل وصول القيم إلى قرار التجاوز. هذا اختبار مقترح للمشروع، والمجموعة المحلية هنا تختبر القارئ على نص واحد في كل استدعاء.

قد يحدد المستخدم خياراً في سطر الأوامر أيضاً. إذا أتاح التطبيق استعمال ملف وإدخال مباشر معاً، فاكتب قاعدة توضّح متى يكون الخيار المباشر بديلاً للقيمة الواردة في الملف. احتفظ بمصدر القيمة المختارة في سجل المهمة عند الحاجة. رسالة تقول إن القيمة الفعلية جاءت من خيار التشغيل تساعد في تفسير اختلافها عن نص الملف. أما وجود اسمين في كائن واحد فيبقى خطأ قراءة حتى لو كان خيار التشغيل سيغير قيمته لاحقاً. بذلك يمكن إصلاح الملف نفسه وتظل مهمات أخرى قادرة على قراءته دون الاعتماد على وجود الخيار المباشر.

يمكن أن يمر وصف المشهد من محرر بصري إلى تطبيق آخر يقرأ JSON. حدد اللحظة التي تملك فيها النص الأصلي. إذا أعطاك المحرر كائناً جاهزاً بعد التحليل، فلا يمكنك أن تطلب من الخطاف استعادة الأزواج التي اختفت. اطلب تصدير النص إذا كانت المراجعة تعتمد على ظهوره، أو اجعل المكون الأول الذي يستقبل الملف يطبق سياسة التكرار. هذا مهم خصوصاً عندما تقارن بين ملف مرفوض في أداة وملف مقبول في أداة أخرى. تأكد أولاً أن الأداتين قرأتا البايتات نفسها وأن كلاً منهما تلقى النص قبل أي إعادة ترتيب أو إعادة كتابة.

هناك أيضاً فرق بين حفظ النص للرجوع إليه وحفظ الإعداد الذي شُغّل به المشروع. النص يكشف كيف كُتبت الأسماء ومن أين جاءت، ويتيح مقارنة ترتيب التعديلات. الإعداد المقروء يوضح القيم التي استخدمتها المهمة بعد نجاح القراءة والدمج والتحقق. إذا احتجت إلى الاثنين، سجلهما باسمين يصفان دورهما. يمكن حفظ بصمة النص للمقارنة داخل المشروع دون نقل محتواه كله إلى سجل مشترك، مع إبقاء تفاصيل الخطأ اللازمة للعمل. احرص على ألا يتضمن سجل التشغيل نص إعداد يحوي قيماً خاصة لا يحتاج المراجع إلى رؤيتها.

## صمم فحصاً يفسر الخطأ لصاحب الملف

تستطيع أداة مشروع صغيرة أن تعرض اسم الملف لأن المستدعي هو الذي فتحه. عند ورود `DuplicateKeyError` يمكنها أن تذكر الاسم المعاد في نص الرسالة وتطلب مراجعة الكائن الذي يحويه. في مشروع فيه مفاتيح مثل `x` تحت عدة كائنات، قد لا يعرف القارئ أي موضع أطلق الخطأ من اسم المفتاح وحده. حتى تضيف موضعاً دقيقاً، تحتاج إلى معلومة لم ينتجها الخطاف الحالي. صمم رسالة صادقة تقول ما عرفته من الشيفرة فعلاً، ثم أضف طريقة للبحث في المصدر أو طبقة تشخيص إذا دعت الحاجة.

إذا ظهرت عدة أخطاء في ملف واحد، يتوقف المثال عند أول تكرار يصل إليه الخطاف. بعد إصلاحه، قد يظهر تكرار آخر في القراءة التالية. هذا السلوك يكفي عندما تكون ملفات الإعداد قصيرة ويحتاج التطبيق إلى قرار قبول أو رفض. قد يحتاج محرر تفاعلي إلى إظهار قائمة بالمواضع دفعة واحدة. في تلك الحالة، اختبر مكون تشخيص منفصلاً على نص يحوي تكراراً في جذر الملف وفي كائن داخلي. اترك قرار تشغيل المهمة مرتبطاً بنجاح قراءة موثوقة، حتى لو تطلبت واجهة التحرير طريقة مختلفة لجمع رسائل متعددة.

في ملف قديم تُعدل قيمه يدوياً، من المفيد أن تفرق في سجل الفحص بين خطأ يحتاج قراراً وخطأ يستطيع الكاتب إصلاحه مباشرة. حذف فاصلة زائدة يعيد صلاحية الصياغة عندما يُعرف موضعها. أما ظهور قيمتين معقولتين لنفس المفتاح فيتطلب معرفة القرار المقصود. لذلك لا تجعل رسالة التكرار تعرض اقتراح حذف سطر بعينه من دون سياق. يمكنها أن تذكر ما يعتمد على الإعداد، مثل أمر المعاينة أو مهمة التصدير، بحيث يعرف صاحبه أين يختبر النتيجة بعد التصحيح.

جرّب أيضاً تصميم حالة نجاح مقابلة عندما تراجع أمر التشغيل. استخدم ملفاً جذره كائن، وفي داخله إعدادات مستقلة لمشهدين لكل منهما اسم `seed`. اقرأه من خلال نقطة الدخول التي ترفض التكرار، ثم افحص أن الإعدادين بقيا متاحين. يفصل هذا الاقتراح بين تصحيح قاعدة القراءة وبين خطأ شائع في التطبيق وهو جمع كل المفاتيح في سجل واحد أثناء التحويل. إذا فشل اختبار القبول بعد تركيب القارئ، فراجع التحويل الذي يتبع التحليل قبل أن تغيّر سياسة الخطاف.

عندما تكتب قائمة التحقق الخاصة بمشروعك، ضع لكل طبقة نتيجة يمكن رصدها. القراءة تعطي كائناً أو خطأً محدداً. التحقق البنيوي يبين الحقول المقبولة. الدمج يحدد قيمة تشغيل واحدة ومصدرها. أما المهمة التي تستعمل الإعداد فتعطي مخرجات تقاس وفق اختبارها الخاص. في المثال المحلي نملك دليلاً على القراءة فقط. معرفة الطبقة التي قدّمت النتيجة تساعدك على اختيار اختبار إضافي عند إدخال الدالة في المشروع بدلاً من إسناد كل سلوك التطبيق إلى خطوة واحدة.

أُعد المقال بمساعدة أدوات ذكاء اصطناعي ومراجعة آلية. اختُبرت الشيفرة الأصلية محلياً. الصورة الرئيسية توضح موضوع المقال.

## المصادر

- [Python 3.12 json reference](https://docs.python.org/3.12/library/json.html)
