كتابة كود الواجهات والتوثيق بمساعدة النماذج الكبيرة

في الدروس السابقة، تعلمنا كيفية استخدام أدوات مثل Figma لإكمال تصاميم واجهة المستخدم، وكيفية الاستعانة بالذكاء الاصطناعي لتوليد صفحات أمامية ثابتة بسرعة، وكيفية استخدام Supabase لبناء قواعد بيانات وتحقيق المصادقة الأولية للمستخدمين. الآن يبرز سؤال طبيعي: بعد النقر على تلك الأزرار الديناميكية في الصفحة الأمامية، كيف تُخزَّن البيانات بهدوء في Supabase؟ وعندما نحتاج إلى تنفيذ منطق أعمال أكثر تعقيدًا (مثل المدفوعات المتزامنة، الإرسال المجدول، معالجة البيانات الحساسة)، هل من الآمن أن يتصل الواجهة الأمامية مباشرة بقاعدة البيانات؟

هذا يقودنا إلى حلقة مهمة للغاية في بنية تطوير الويب الحديثة — واجهات API الخلفية.

مقارنة بالماضي حيث كنا نكتب يدويًا مئات الأسطر من مسارات الخادم والمتحكمات ومنطق التحقق من المعلمات، يمكننا اليوم الاستفادة الكاملة من القدرات القوية للنماذج الكبيرة على توليد الكود، وإسناد الكود الأساسي المعقد إلى الذكاء الاصطناعي. في هذا الدرس، سنتجاوز دائرة "الذكاء الاصطناعي يكتب كودًا عامًا وغير دقيق"، ونعتمد على سيناريوهات أعمال حقيقية، لنوضح لك كيفية توجيه النماذج الكبيرة من خلال نصائح (Prompts) عالية الجودة لكتابة واجهات خلفية Node.js قوية ومتوافقة مع معايير الصناعة، مع التوليد التلقائي لوثائق الواجهات وحالات الاختبار.

💡 المعارف المسبقة

قبل دراسة هذا القسم، يُنصح بأن تكون على دراية بالمحتوى التالي:

• من قاعدة البيانات إلى Supabase - فهم مفاهيم قواعد البيانات ونماذج البيانات.
• سير عمل Git و GitHub - الإلمام بكيفية التحكم في الإصدارات أثناء تطوير المشاريع.
• ما هو الطرفية/سطر الأوامر - تهيئة المشاريع وتشغيلها تتطلب عمليات أوامر أساسية.

ما ستتعلمه

1. ما هي واجهات API: فهم الجسر بين الواجهة الأمامية والخلفية ومعايير تصميم RESTful.
2. النماذج الكبيرة تمكّن بناء الخدمات: كيفية استخدام Prompt منظم لجعل الذكاء الاصطناعي يساعدك في بناء مشروع Node.js + Express أساسي.
3. تطوير منطق الواجهات: توجيه النماذج الكبيرة لتوليد واجهات CRUD (إنشاء، قراءة، تحديث، حذف) تتضمن تحققًا صارمًا من الأعمال وربطًا مع قاعدة بيانات Supabase.
4. توثيق الواجهات الآلي: جعل النماذج الكبيرة تولد وثائق OpenAPI/Swagger القياسية للتعاون بين الفرق.
5. الاختبار والتكامل الشامل: استخدام النماذج الكبيرة لتوليد مجموعات اختبار Postman وحالات اختبار Jest الوحدوية لضمان جودة الكود.

---

1. لماذا نحتاج إلى واجهات API؟

في الفهم التقليدي، الواجهة الأمامية هي "الجزء المرئي"، وقاعدة البيانات هي "المخزن". لكن هناك عنصر تنسيق مفقود بينهما. إذا تخيلت التطبيق بأكمله كمطعم:

• الواجهة الأمامية (العميل) هي قائمة الطعام وطاولة الطلب، حيث يتصفح الضيوف الأطباق ويقدمون طلباتهم.
• قاعدة البيانات (مثل Supabase) هي مخزن المطبخ، حيث تُحفظ جميع المكونات والسجلات.
• واجهة API الخلفية هي النادل. لا يمكن للضيوف الدخول مباشرة إلى المطبخ لأخذ المكونات (مما يسبب فوضى ومخاطر أمنية)، بل يقدمون "طلبهم" (HTTP Request) للنادل. يقوم النادل بالتحقق (التحقق من المعلمات، المصادقة والتفويض)، ثم يذهب إلى المطبخ لإحضار المحتوى المطلوب، ويعيد "الطبق الجاهز" (HTTP Response، عادةً بتنسيق JSON) للضيف.

من خلال واجهات API، نحقق فصلًا واضحًا بين الواجهة الأمامية والخلفية: الواجهة الأمامية تهتم فقط بكيفية عرض الصفحات، بينما تركز الخلفية على منطق الأعمال ومعالجة البيانات والحماية الأمنية.

---

2. تصميم بنية المشروع والتهيئة

هيكل مشروع واضح هو شرط مسبق لقدرة النماذج الكبيرة على كتابة كود جيد. قبل أن نطلب من الذكاء الاصطناعي كتابة الكود، يجب أن نكون واضحين بشأن الهيكل الهندسي.

2.1 هيكل مشروع API الشائع

حتى عند استخدام النماذج الكبيرة لتوليد الكود، يجب ألا نضع كل الكود في ملف server.js واحد. بنية خلفية Node.js سهلة الصيانة تبدو عادةً كما يلي:

my-api-project/
├── .env                  # متغيرات البيئة الحساسة (مثل مفاتيح API، سلسلة اتصال قاعدة البيانات)
├── server.js             # نقطة دخول المشروع (تشغيل الخادم، تسجيل الوسائط العامة)
├── package.json          # ملف إدارة التبعيات
├── src/
│   ├── routes/           # طبقة المسارات: تحديد مسارات URL وطرق الطلب
│   ├── controllers/      # طبقة المتحكمات: معالجة معلمات الطلب، استدعاء الخدمات وإرجاع الاستجابة
│   ├── services/         # طبقة الخدمات: تغليف التفاعل مع قاعدة البيانات ومنطق الأعمال الأساسي
│   └── middlewares/      # الوسائط: المصادقة، التقاط الأخطاء العامة
└── docs/                 # دليل تخزين وثائق API

2.2 الاستعانة بالذكاء الاصطناعي لتهيئة المشروع

بدلاً من تشغيل npm init يدويًا وتثبيت التبعيات واحدة تلو الأخرى، يمكنك تقديم المواصفات أعلاه كـ Prompt للنموذج الكبير:

🗣️ نصيحة للنموذج الكبير (مثال على Prompt): "ساعدني في بناء مشروع خلفي Node.js، يجب أن يتمكن من الاتصال بقاعدة بيانات Supabase، ببنية واضحة تسهل الصيانة المستقبلية."

بعد تشغيل الكود الذي يعيده الذكاء الاصطناعي، ستحصل على تطبيق خلفي بمعالم مستوى المؤسسات على localhost:3000.

---

3. التطبيق العملي الأساسي: تطوير الواجهات بمساعدة النماذج الكبيرة

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

لنأخذ واجهة إضافة عنصر جديد في جدول menu_items (جدول القائمة) المذكور في فصل قاعدة البيانات، لنرَ كيف نكتب Prompt عالي الجودة.

3.1 تزويد النموذج الكبير بسياق كامل

قبل طلب كتابة واجهة من الذكاء الاصطناعي، يجب تقديم تعريف حقول قاعدة البيانات (Schema) وشروط القيود المحددة.

🗣️ قالب نصيحة عالي الجودة (Prompt): "ساعدني في كتابة واجهة إضافة عنصر جديد للقائمة، العنصر يحتوي على اسم المنتج، السعر، الفئة (برجر، مقبلات، مشروبات)، وحالة التفعيل. اسم المنتج والسعر مطلوبان، والسعر لا يمكن أن يكون سالبًا. عند إدخال مستخدم غير صحيح يجب إظهار رسالة خطأ."

3.2 مراجعة الكود المُولَّد من النموذج الكبير

الكود المُولَّد من النموذج الكبير عادةً ما يقسم المسؤوليات بوضوح كما يلي:

// services/menuService.js
const { createClient } = require('@supabase/supabase-js');
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);

exports.createMenuItem = async (menuData) => {
    // استدعاء Supabase SDK لإدراج البيانات في الجدول
    const { data, error } = await supabase
        .from('menu_items')
        .insert([menuData])
        .select();

    if (error) throw new Error(`فشل إدراج قاعدة البيانات: ${error.message}`);
    return data[0];
};

يمكنك ملاحظة أن الكود المُولَّد بهذه الطريقة ليس منظمًا فحسب، بل يأخذ في الاعتبار تهيئة Supabase والتقاط الأخطاء ومعالجة الاستثناءات، مما يختلف اختلافًا جوهريًا عن كود السباغيتي (Spaghetti Code) الذي تحصل عليه عندما تطلب ببساطة "اكتب واجهة إضافة".

---

4. تحرير اليدين: التوليد التلقائي لوثائق الواجهات

بالنسبة لفريق التطوير، واجهة API بدون وثائق هي صندوق أسود. لا يمكن للمهندسين الأماميين تخمين المعلمات المطلوبة أو توقع بنية الاستجابة. المعيار الأكثر شيوعًا لوصف API في الصناعة هو OpenAPI (المعروف سابقًا باسم Swagger).

في الماضي، كانت كتابة وثائق Swagger بصيغة YAML أو JSON يدويًا مؤلمة للغاية وعرضة للأخطاء. الآن، أصبح هذا المجال من أكثر ما تتميز به النماذج الكبيرة.

يمكنك ببساطة تحديد كود routes و controllers الذي كتبته للتو وإرساله للنموذج الكبير:

🗣️ نصيحة لتوليد الوثائق: "ساعدني في توليد وثائق واجهات بناءً على الكود أعلاه، مع توضيح معنى كل معلمة والبيانات المُعادة، لتسهيل التعاون مع الزملاء في الواجهة الأمامية."

في هذه العملية، يمكنك حتى طلب من الذكاء الاصطناعي إكمال أوصاف الحقول (Description) وبيانات Mock (مثل price_cents: 1200 يمثل 12 دولارًا)، مما يقلل بشكل كبير من تكلفة التواصل.

---

5. الحماية والضمان: توليد كود الاختبار ومجموعات Postman

بعد كتابة الكود وإعداد الوثائق، يتبقى خطوة أخيرة: التحقق من أن الكود يعمل بالفعل.

5.1 توليد إعدادات اختبار Postman / Apifox

في تطوير الواجهات، نستخدم عادةً أدوات مرئية مثل Postman لمحاكاة طلبات HTTP من الواجهة الأمامية. بدون استخدام النماذج الكبيرة، ستحتاج إلى إدخال URL يدويًا، وإضافة Headers (رؤوس الطلب) واحدًا تلو الآخر، وتجميع نص طلب JSON.

يكفي أن ترسل للذكاء الاصطناعي التعليمات التالية:

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

بعد الحصول على نص JSON، احفظه باسم menu_api.json واسحبه إلى Postman، وستحصل فورًا على لوحة نقر اختبار جاهزة للاستخدام.

5.2 كتابة اختبارات وحدوية آلية

إذا كنت تسعى لجودة هندسية أكثر صرامة، يمكنك جعل النموذج الكبير يساعدك في استخدام أطر اختبار مثل Jest لكتابة اختبارات وحدوية (Unit Tests)، وإجراء اختبارات حدودية على منطق الأعمال الأساسي (مثل التحقق مما إذا كانت طبقة قاعدة البيانات ترفض الأسعار السالبة).

---

6. أفضل الممارسات الأساسية لواجهات الخلفية

حتى مع مساعدة الذكاء الاصطناعي، بصفتك "الحارس" للنظام بأكمله، لا يزال يتعين عليك فهم ومراجعة المبادئ الأساسية التالية:

1. تسمية المسارات وفق معايير RESTful:
   • تصميم جيد: GET /api/users (الحصول على قائمة المستخدمين)، POST /api/users (إنشاء مستخدم). يجب أن يمثل URL اسم "المورد".
   • تصميم خاطئ: POST /api/getUser أو POST /api/createUser. يجب ترك الأفعال لطرق HTTP (GET/POST/PUT/DELETE).
2. رموز حالة HTTP القياسية:
   • 200/201: نجاح الطلب / إنشاء المورد بنجاح.
   • 400: طلب غير صحيح، خطأ في تنسيق معلمات الواجهة الأمامية أو حقل مطلوب مفقود.
   • 401/403: غير مصادق / ممنوع، المستخدم لم يسجل الدخول أو ليس لديه صلاحية.
   • 404: غير موجود، المورد غير موجود.
   • 500: خطأ في الخادم، خطأ في كود الخلفية أو قاعدة البيانات معطلة. يجب تجنب كشف تتبع الخطأ مباشرة للواجهة الأمامية (مخاطر أمنية).
3. لا تثق أبدًا في مدخلات المستخدم: مدخلات الواجهة الأمامية قد تكون مزيفة، يجب إعادة التحقق من جميع المعلمات الأساسية في واجهات الخلفية.

7. الخلاصة

من خلال تعلم هذا الفصل، حققت تحولًا حقيقيًا في منظور التطوير: لم تعد عالقًا في بناء الجملة وعلامات الترقيم كـ "كاتب كود"، بل ارتقيت لتصبح مصمم أنظمة وقائد بنية.

لقد أتقنت:

1. التفكير النظامي الأساسي لـ واجهات API وفصل الواجهة الأمامية عن الخلفية.
2. كيفية تحسين جودة الكود الخلفي المُولَّد من النماذج الكبيرة بشكل كبير من خلال توفير السياق ومفهوم البنية الطبقية.
3. تحويل المهام الشاقة لـ كتابة الوثائق وبناء حالات الاختبار بمهارة إلى مهام آلية يتقنها الذكاء الاصطناعي.
4. بالدمج مع معرفتك السابقة بـ Supabase، ربطت تدفق البيانات الكامل من طلب العميل إلى تحديث قاعدة البيانات الأساسية.

💡 الخطوة التالية

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