اجعل الكود المولد قابلاً للصيانة: قاعدة الهندسة المملة

لماذا صيانة الكود المولد أصعب

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

المخرجات المولدة غالبًا تبدو جيدة بمعزلها. التكاليف تظهر عند التغيير الثاني أو الثالث: لا يمكنك تحديد مكان انتماء جزء ما، تصلح نفس السلوك في مكانين، أو تتجنب لمس ملف لأنك لا تعرف ماذا سيؤثر عليه ذلك.

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

الهندسة المملة هي العكس: حدود واضحة، أسماء عادية، وإعدادات افتراضية بديهية. الأمر ليس عن الكمال. إنه اختيار تخطيط يمكن لزميل متعب (أو أنت في المستقبل) فهمه في 30 ثانية.

هدف بسيط: اجعل التغيير التالي سهلًا، وليس مثيرًا للإعجاب. هذا عادة يعني مكانًا واضحًا لكل نوع من الكود (UI، API، البيانات، الأدوات المشتركة)، أسماء متوقعة تطابق ما يفعله الملف، وأقل قدر من “السحر” مثل الربط التلقائي، المتغيرات العالمية المخفية، أو البرمجة التعريفية.

مثال: إذا طلبت من Koder.ai إضافة "دعوات الفريق"، تريد أن يضع واجهة المستخدم في منطقة الواجهة، ويضيف مسار API واحد في منطقة الـ API، ويخزن بيانات الدعوات في طبقة البيانات، دون اختراع مجلد أو نمط جديد فقط لهذه الميزة. تلك الاتساق الممل هو ما يحافظ على بساطة التعديلات المستقبلية.

قاعدة الهندسة المملة

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

يجب أن تكون قادرًا على الإجابة على هذه الأسئلة بسرعة:

• أين تعيش هذه الميزة؟
• أين أضع ملفًا جديدًا؟
• ماذا أسميه؟
• ما أبسط مسار من الواجهة إلى البيانات؟

القاعدة

اختر بنية عادية والتزم بها في كل مكان. عندما يقترح أداة (أو زميل) نمطًا أنيقًا، الإجابة الافتراضية هي "لا" ما لم يزيل ألمًا حقيقيًا.

إعدادات عملية تصمد عبر الزمن:

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

اختبار ذهني سريع

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

تعمل هذه القاعدة بشكل جيد خاصة مع أدوات البرمجة السريعة مثل Koder.ai: يمكنك التوليد بسرعة، لكنك لا تزال توجه المخرجات داخل نفس الحدود المملة في كل مرة.

حدود المجلدات البسيطة التي تتدرج

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

تخطيط أعلى صغير يتناسب مع العديد من تطبيقات الويب:

• app/ للشاشات، التوجيه، وحالة الصفحة-level
• components/ قطع واجهة مستخدم قابلة لإعادة الاستخدام
• features/ مجلد واحد لكل ميزة (billing، projects، settings)
• api/ كود عميل API ومساعدي الطلب
• server/ معالجات الخلفية، الخدمات، وقواعد العمل

هذا يجعل الحدود واضحة: واجهة المستخدم تعيش في app/ و components/، مكالمات الـ API تعيش في api/، ومنطق الخلفية في server/.

وصول البيانات يجب أن يكون مملًا أيضًا. احتفظ باستعلامات SQL وكود المستودعات بالقرب من الخلفية، لا متناثرة عبر ملفات الواجهة. في إعداد Go + PostgreSQL بسيط، القاعدة: معالجات HTTP تنادي الخدمات، الخدمات تنادي المستودعات، والمستودعات تتحدث إلى قاعدة البيانات.

الأنواع والأدوات المشتركة تستحق منزلًا واضحًا، لكن اجعلها صغيرة. ضع الأنواع العابرة في types/ (DTOs، enums، واجهات مشتركة) والمساعدين الصغار في utils/ (تنسيق التواريخ، المحققات البسيطة). إذا بدأ utils/ يشعر كأنه تطبيق ثانٍ، فالكود على الأرجح ينتمي إلى مجلد ميزة بدلاً من ذلك.

المولد مقابل الكود المكتوب يدويًا

عامل المجلدات المولدة على أنها قابلة للاستبدال.

• ضع الناتج المولد في generated/ (أو gen/) وتجنّب تحريره مباشرة.
• احتفظ بالمنطق المخصص في features/ أو server/ حتى لا تكتبه عملية إعادة التوليد.
• إذا اضطررت لتصحيح سلوك مولد، لفّه (ملف محول) بدلًا من تعديل المصدر.

مثال: إذا ولّد Koder.ai عميل API، خزّنه تحت generated/api/، ثم اكتب أغطية رقيقة في api/ حيث يمكنك إضافة إعادة المحاولة، التسجيل، أو رسائل خطأ أوضح بدون لمس الملفات المولدة.

اتفاقيات التسمية التي تمنع الالتباس

الكود المولد سهل الإنشاء وسهل التكديس. التسمية هي ما يبقيه قابل القراءة بعد شهر.

اختر نمط تسمية واحد ولا تخلطه:

• المجلدات والملفات: kebab-case (user-profile-card.tsx, billing-settings)
• مكونات React: PascalCase (UserProfileCard)
• الدوال والمتغيرات: camelCase (getUserProfile)
• الثوابت: SCREAMING_SNAKE_CASE (MAX_RETRY_COUNT)

سمِّ بحسب الدور، لا بحسب كيفية عمله اليوم. user-repository.ts هو دور. postgres-user-repository.ts تفصيل تنفيذي قد يتغير. استخدم لاحقات التنفيذ فقط عندما يكون لديك فعلاً عدة تنفيذات.

تجنّب أدراج الفوضى مثل misc، helpers، أو utils العملاقة. إذا كانت الدالة مستخدمة من ميزة واحدة فقط، احتفظ بها بالقرب من تلك الميزة. إذا كانت مشتركة، اجعل الاسم يصف القدرة (date-format.ts, money-format.ts, id-generator.ts) واحفظ الوحدة صغيرة.

اتفاقيات تجعل التنقل أسرع

عندما تتبع المسارات، المعالجات، والمكونات نمطًا، يمكنك إيجاد الأشياء بدون بحث:

• المسارات: routes/users.ts مع مسارات مثل /users/:userId
• المعالجات (HTTP): handlers/users.get.ts, handlers/users.update.ts
• الخدمات (قواعد العمل): services/user-profile-service.ts
• الوصول إلى البيانات: repositories/user-repository.ts
• مكونات الواجهة: components/user/UserProfileCard.tsx

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

افتراضات بدون تعقيد (قواعد إرشادية)

الكود المولد قد يبدو مثيرًا في اليوم الأول ومؤلمًا في اليوم الثلاثين. اختر افتراضات تجعل الكود بديهيًا، حتى إن كان متكررًا قليلًا.

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

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

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

قواعد إرشادية تبقي الفرق متناسقة:

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

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

إذا ولّدت تطبيقًا بـ Koder.ai، اطلب هذه الافتراضات مقدمًا: توصيل وحدات صريح، إعداد مركزي، ونمط خطأ واحد.

حدود بين الواجهة، الـ API، والبيانات

خطوط واضحة بين الواجهة، الـ API، والبيانات تحافظ على احتواء التغييرات. معظم الأخطاء الغامضة تحدث عندما تبدأ طبقة ما بعمل مهمة طبقة أخرى.

الواجهة: عرض الحالة وجمع الإدخال

اعتبر الواجهة (غالبًا React) مكانًا لعرض الشاشات وإدارة حالة واجهة المستخدم فقط: أي تبويب مفتوح، أخطاء النماذج، مؤشرات التحميل، والتعامل الأساسي مع الإدخال.

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

الـ API: أشكال رفيعة ومستقرة

اجعل طبقة الـ API متوقعة. يجب أن تترجم طلبات HTTP إلى استدعاءات للكود التجاري، ثم ترجمة النتائج إلى أشكال طلب/استجابة مستقرة. تجنّب إرسال نماذج قاعدة البيانات مباشرة عبر الشبكة. الاستجابات المستقرة تتيح لك إعادة بناء الداخليّات دون كسر الواجهة.

مسار بسيط يعمل جيدًا:

• الواجهة تنادي عميل API بأشياء طلب/استجابة بنمط مضبوط.
• معالجات الـ API تتحقق من المدخلات وتستدعي طريقة خدمة.
• الخدمات تحتوي قواعد العمل وتدفقات العمل.
• المستودعات تخفي استعلامات قاعدة البيانات وراء طرق صغيرة.

البيانات: اخفِ الاستعلامات خلف المستودعات

ضع SQL (أو منطق ORM) خلف حد المستودع حتى لا “يعرف” بقية التطبيق كيف تُخزن البيانات. في Go + PostgreSQL، هذا عادة يعني مستودعات مثل UserRepo أو InvoiceRepo مع طرق صغيرة وواضحة (GetByID, ListByAccount, Save).

مثال ملموس: إضافة رموز خصم. الواجهة تعرض حقلًا وتعرض السعر المحدّث. الـ API يقبل code ويُرجع {total, discount}. الخدمة تقرر إن كان الرمز صالحًا وكيف تتراكم الخصومات. المستودع يجلب ويسجل الصفوف المطلوبة.

خطوة بخطوة: إعداد كود مولد قابل للصيانة

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

سير عملي عملي

ابدأ بمراجعة تخطيط قصيرة. إذا استخدمت Koder.ai، وضعه في وضع التخطيط لكتابة خريطة المجلدات وبعض قواعد التسمية قبل توليد أي شيء.

ثم اتبع هذا الترتيب:

1. حدد الخريطة والقواعد كتابةً. اختر الحدود (على سبيل المثال: ui/, api/, data/, features/) وقليل من قواعد التسمية.
2. ولّد شريحة رأسية رفيعة واحدة. اختر ميزة صغيرة تلمس الواجهة، الـ API، والتخزين، مثل "إنشاء جهة اتصال." الهدف هو المسار الشامل، ليس الاكتمال.
3. أعد الهيكلة فورًا لتطابق الحدود. انقل الكود إلى المجلدات المخططة، أعد تسمية الملفات الغامضة، واحذف الازدواج. قسم الدوال التي "تفعل كل شيء" إلى واجهة، معالج، ووصول بيانات.
4. أضف ميزة ثانية لاختبار الشكل. اختر شيء مشابه، مثل "قائمة جهات الاتصال." إذا شعرت أنك مضطر لكسر قواعدك، فربما الحدود خاطئة.
5. ثبت الاتفاقيات مبكرًا. أضف CONVENTIONS.md قصيرًا وتعامل معه كعقد. عندما يكبر قاعدة الكود، يصبح تغيير الأسماء وأنماط المجلدات مكلفًا.

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

سيناريو مثال: إضافة ميزة بدون فوضى

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

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

تخطيط نظيف قد يبدو هكذا:

• web/src/pages/ContactsPage.tsx و web/src/components/ContactForm.tsx
• server/internal/http/contacts_handlers.go
• server/internal/service/contacts_service.go
• server/internal/repo/contacts_repo.go
• server/migrations/

الآن تصبح "العلامات" متوقعة. عدِّل المخطط (جدول contact_tags جديد أو عمود tags)، ثم اعمل على كل طبقة على حدة: المستودع يقرأ/يكتب العلامات، الخدمة تتحقق، المعالج يعرض الحقل، والواجهة تعرضه وتحرره. لا تُدخل SQL في المعالجات أو قواعد العمل في مكونات React.

إذا طلب المنتج لاحقًا "تصفية حسب العلامة"، ستعمل غالبًا في ContactsPage.tsx (حالة الواجهة ومعاملات الاستعلام) ومعالج HTTP (تحليل الطلب)، بينما يتعامل المستودع مع الاستعلام.

بالنسبة للاختبارات والبيانات التجريبية، احتفظ بالأشياء صغيرة وقريبة من الكود:

• server/internal/service/contacts_service_test.go لقواعد مثل "أسماء العلامات يجب أن تكون فريدة لكل جهة"
• server/internal/repo/testdata/ لبيانات تجريبية بسيطة
• web/src/components/__tests__/ContactForm.test.tsx لسلوك النموذج

إذا كنت تولد هذا بـ Koder.ai، نفس القاعدة تنطبق بعد التصدير: احتفظ بالمجلدات مملة، الأسماء حرفية، والتعديلات تتوقف عن الشعور كأنها أثر آثار.

أخطاء شائعة تجعل التغييرات المستقبلية مكلفة

الكود المولد قد يبدو نظيفًا في اليوم الأول ومع ذلك مكلفًا لاحقًا. الجاني المعتاد ليس "الكود السيئ" بقدر ما هو التنافر.

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

فخ آخر هو خلط الطبقات. عندما يتحدث مكون واجهة إلى قاعدة البيانات، أو يبني معالج API SQL، تتحول التغييرات الصغيرة إلى تعديلات خطرة عبر التطبيق. حافظ على الحد: الواجهة تنادي الـ API، الـ API ينادي الخدمة، والخدمة تنادي الوصول إلى البيانات.

الإفراط في التجريدات العامة مبكرًا أيضًا يضيف تكلفة. إطار "BaseService" أو "Repository" عام يبدو أنيقًا، لكن التجريدات المبكرة هي تخمينات. عندما تتغير الحقيقة، تقاتل إطارك بدلاً من الشحن.

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

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

قائمة تحقق سريعة قبل الإطلاق

إذا فتح شخص جديد المستودع، يجب أن يكون قادرًا على الإجابة على سؤال واحد بسرعة: "أين أضيف هذا؟"

اختبار التنقل في دقيقتين

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

تحقق من ثلاثة منازل واضحة:

• تغييرات الواجهة تعيش في مكان واضح واحد.
• مسارات/معالجات الـ API سهلة العثور انطلاقًا من الواجهة.
• نموذج البيانات وتغييرات قاعدة البيانات لها موقع واضح.

قواعد تستحق الإنفاذ في المراجعة

• الواجهة، الـ API، والبيانات لكلٍ منها منزل، والاستثناءات نادرة.
• الأسماء تُقرأ كملصقات، وليس ألغازًا.
• أخطاء كسر الطبقات يتم تمييزها (مثل الواجهة التي تصل إلى قاعدة البيانات).
• الاختصارات الذكية تُرفض افتراضيًا.

إذا كان منصتك تدعم ذلك، احتفظ بمسار استرجاع. اللقطات والاسترجاع مفيدة خاصة عند التجريب في البنية وتريد طريقة آمنة للعودة.

الخطوات التالية: اجعلها مملة، اجعلها رخيصة

تحسن القابلية للصيانة أسرع عندما تتوقف عن مناقشة الأسلوب وتبدأ باتخاذ قرارات قليلة تستمر.

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

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

إذا كنت تبني مع Koder.ai (koder.ai)، فالأمر مفيد لحفظ هذه الاتفاقيات كموجه بداية حتى تهبط كل توليدة جديدة في نفس البنية. الأداة يمكنها أن تتحرك بسرعة، لكن الحدود المملة هي ما تُبقي الكود سهل التغيير.