دليل المعمارية.

ما هي المعمارية (وما ليست)

"المعمارية هي مجموعة القرارات التي يكون تغييرها لاحقًا مكلفًا." - Ralph Johnson

المعمارية ليست "أي framework استخدمنا" - هذا تفصيل تنفيذي. المعمارية هي الشكل الذي تشعر به عند تصفّح قاعدة الكود: كيف تُقسَّم الوحدات، وفي أي اتجاه تتدفّق التبعيات، وأي كود يمكنه استدعاء أيّ كود.

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

تكلفة القرارات

تظهر التكلفة الحقيقية للقرار المعماري ليس عند اتخاذه، بل مع تزايد عدد القرارات اللاحقة المبنية عليه. ثلاثة مقاييس:

• زمن التراجع - كم أسبوعًا للتراجع؟
• سطح الانتشار - كم عدد الملفات / الوحدات التي تعتمد على هذا القرار؟
• العبء المعرفي - كم ساعة يحتاج مطوّر جديد لفهمه؟

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

النية مقابل التنفيذ

المعمارية هي مجموعة القرارات التي قصدتها؛ أما قاعدة الشيفرة فهي ما بُني فعلًا. الفجوة بينهما هي الانحراف المعماري - وتنمو بهدوء حتى يستغرق تغييرٌ كان يجب أن يأخذ ساعةً أسبوعًا كاملًا.

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

الطبقي (متعدد الطبقات)

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

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

السداسي · المنافذ والمحوّلات

يقع المجال في المركز ولا يعرف شيئًا عن العالم الخارجي. كل ما هو خارجي - قاعدة البيانات وHTTP وطابور الرسائل - يتحدث إليه عبر منافذ (واجهات) تنفّذها المحوّلات.

العائد هو قابلية الاختبار والاستبدال: يمكنك استبدال Postgres بنسخة وهمية في الذاكرة أثناء الاختبارات، أو REST بـ gRPC، دون لمس سطر واحد من شيفرة المجال.

Clean Architecture

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

يمنحك مجالًا يُترجَم ويُختبَر دون أي بنية تحتية. الثمن هو الطقوس - مزيد من الواجهات ومزيد من التحويل. يستحق العناء للأنظمة طويلة العمر، ومبالغٌ فيه للوحة إدارة CRUD.

DDD - التصميم الموجَّه بالمجال

DDD ليس framework - إنه انضباط في المصطلحات. "Aggregate" و"bounded context" و"anti-corruption layer" - لغة مشتركة للحديث عن المشكلة.

متى DDD؟

• النطاق معقّد، وغالبًا ما يُخلَط بينه وبين التعقيد التقني.
• تعمل عدة فرق على النطاق نفسه.
• يتحدّث جانب الأعمال وجانب الهندسة بلغتين مختلفتين.

DDD ليس لكل مشروع. إذا بدا ثقيلًا للوحة إدارة كثيفة الـ CRUD، فهو على الأرجح كذلك.

كرة الطين الكبيرة

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

لا تُعيد كتابة كرة الطين - بل تخنقها. غلِّف وصلةً، وانقل قدرةً واحدة خلف واجهة نظيفة، ثم كرِّر. تُظهر لك خريطة التبعيات في AppArch أين توجد الوصلات بالفعل.

نمط مضاد: وحدة الإله

"وحدة الإله" هي تلك التي تُستدعى من كل مكان وتحتوي على كل شيء. أسماء مثل Utils وCommon وShared هي علامات تحذير.

# قاعدة تكتشف ذلك
- id: GOD-001
  max_fan_in: 25
  message: "Module imported by >25 files - split or rename"

الحل: قسّمها إلى ثلاثة تقريبًا. المجموعة الأولى بنية تحتية حقيقية (logger، config). المجموعة الثانية أوّليات النطاق (money، id). المجموعة الثالثة - على الأرجح وحدة منفصلة مختبئة هناك.

التبعيات الدائرية

الوحدة A تحتاج B، وB تحتاج A. الآن لا يمكن فهم أيٍّ منهما أو اختباره أو نشره وحده، ويصبح ترتيب البناء كرمي عملة. الدورات هي أوثق مؤشر على وحدةٍ لا أحد يريد لمسها.

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

التجريدات المُتسرِّبة

يتسرّب التجريد عندما يتعيّن عليك معرفة كيفية تنفيذه لاستخدامه بشكل صحيح - مستودعٌ يرمي استثناءات SQL، أو ذاكرة تخزينٍ تُجبر المستدعين على معالجة التقادم. وعد بإخفاء تفصيلٍ ولم يفعل.

إمّا أن تسدّ التسرّب - بترجمة أخطاء التنفيذ عند الحدود - أو تتخلّى عن التجريد. التجريد المتسرّب أسوأ من عدمه: تدفع ثمن الوساطة دون أن تحصل على العزل.

مراجعة المعمارية

المراجعة ليست بوابة تمنع الدمج؛ بل حوارٌ حول ما إذا كان التغيير يقرّب النظام من شكله المقصود أم يبعده عنه. أفضل المراجعات تسأل «ما الذي سيُصعّبه هذا لاحقًا؟» أكثر من «هل هذا صحيح الآن؟»

أبقِها خفيفة ومستمرة. مراجعةٌ قصيرة على كل طلب دمج مهم خيرٌ من مجلس معمارية فصلي يتحايل عليه الجميع.

سجلات قرارات المعمارية

يلتقط الـ ADR قرارًا واحدًا: السياق، والخيارات المدروسة، والاختيار، ونتائجه - فقرة أو فقرتان، مُؤرشَفة بجانب الشيفرة. بعد ستة أشهر يجيب عن السؤال الوحيد المهم: لماذا هو هكذا؟

اكتب الـ ADR عند اتخاذ القرار، لا بعده. استبدِله بدل حذفه - أثرُ سبب تغيير رأيك لا يقل قيمةً عن الإجابة الحالية.

إعادة الهيكلة الكبيرة

إعادة الهيكلة الكبيرة التي تصل كدمجٍ عملاق واحد هي إعادة كتابةٍ متنكّرة - وتُلغى أول مرة تتعطّل فيها. إعادة الهيكلة الحقيقية سلسلةٌ من خطواتٍ صغيرة تحافظ على السلوك، كلٌّ منها قابلة للشحن وحدها.

أضِف المسار الجديد بجانب القديم، ورحِّل المستدعين تدريجيًا، ثم احذف المسار القديم. الاختبارات هي حبل الأمان؛ بدونها لا تُعيد الهيكلة، بل تقامر.