نادرًا ما يتعلق هندسة البرمجيات بإيجاد إجابة "صحيحة" واحدة. إنها سلسلة من التنازلات التي تُتخذ تحت قيود محددة، بدافع سياق الوقت. ومع ذلك، غالبًا ما يختفي السبب وراء اختيار تقنية قاعدة بيانات جديدة أو إعادة هيكلة النظام الأحادي (Monolith) في الهواء. وبعد أشهر، ينظر المطورون الجدد إلى الكود القديم ويتساءلون: "لماذا اخترنا MongoDB بدلاً من PostgreSQL؟"
هنا يأتي دور سجلات القرارات المعمارية (ADRs). يعد ADR مستندًا يلتقط قرارًا معماريًا مهمًا تم اتخاذه، جنبًا إلى جنب مع سياقه ونتائجه. فهو يعمل كسجل لتطور برمجياتك، ويوفر للمشرفين المستقبليين فهم لماذا تم اتخاذ القرار، وليس فقط ماذا تم فعله.
لماذا تعتبر ADRs مهمة؟
بدون توثيق، تصبح المعرفة المعمارية معرفة قبلية (tribal knowledge). فهي تعيش في أذهان المهندسين ذوي الخبرة الذين قد يغادرون الشركة. تعمل ADRs على ديمقراطية هذه المعرفة. فهي تسمح للفرق بـ:
- تتبع تطور التصميم: فهم كيفية تغير النظام بمرور الوقت.
- تقليل إرهاق اتخاذ القرار: الرجوع إلى القرارات السابقة لتجنب إعادة مناقشة القضايا التي تم حسمها بالفعل.
- تحسين عملية الاندماج (Onboarding): يمكن لأعضاء الفريق الجدد فهم الديون التقنية والسياق التاريخي بسرعة.
- تسهيل المراجعات الأفضل: يمكن للزملاء طرح أسئلة حول القرارات بناءً على السياق بدلاً من التفضيلات الشخصية.
تنسيق ADR القياسي
بينما يمكن أن تختلف التنسيقات، فإن النهج الذي شهّره مايكل نيغارد وموقع ADR.org يوفر هيكلًا قويًا. يجب أن يتضمن ADR الجيد ما يلي:
- العنوان: معرّف فريد وموجز (على سبيل المثال، 001-use-postgres).
- الحالة: مقترح، مقبول، متروك، أو محل استبدال.
- السياق: القوى الدافعة المؤثرة، بما في ذلك القيود التقنية أو التنظيمية أو التنظيمية (Regulatory).
- القرار: التغيير أو الاختيار الفعلي الذي تم اتخاذه.
- النتائج: المفاضلات الناتجة، سواء كانت إيجابية أو سلبية.
التنفيذ العملي
أفضل مكان لتخزين سجلات ADRs هو بجانب كود المصدر الخاص بك، وعادةً في دليل يحمل اسم docs/adr. يضمن ذلك أن يخضع التوثيق لنظام التحكم في الإصدارات (Version Control) جنبًا إلى جنب مع الكود، مما يمنع تباعد التوثيق عن الكود.
إليك قالب لإنشاء ADR باستخدام Markdown:
## 002-adopt-event-sourcing
**الحالة**: مقبول
**التاريخ**: 2023-10-27
### السياق
يعاني هيكلنا الحالي القائم على CRUD من صعوبات في متطلبات التدقيق (Audit) واتساق البيانات عبر الخدمات المصغرة (Microservices). نحتاج إلى طريقة لتتبع كل تغيير في حالة كيان الأعمال للامتثال والتحليلات في الوقت الفعلي.
### القرار
سنعتمد نمط Event Sourcing (تتبع الأحداث) لخدمة إدارة الطلبات. بدلاً من تخزين الحالة الحالية للطلب، سنخزن سلسلة من الأحداث (مثل `OrderCreated`، `ItemAdded`، `OrderShipped`).
### النتائج
* **إيجابي**: مسار تدقيق كامل؛ سهولة تنفيذ نمط CQRS؛ يدعم إعادة تشغيل الأحداث لأغراض تصحيح الأخطاء.
* **سلبي**: زيادة التعقيد في التعامل مع إعادة بناء الحالة؛ اتساق متأخر (Eventual Consistency) في نماذج القراءة؛ منحنى تعليمي للفريق.أفضل الممارسات للتبني
لجعل سجلات ADRs فعالة، اتبع هذه الإرشادات:
- حافظ على خفتها: يجب أن يكون ADR ملخصًا، وليس أطروحة طويلة. إذا وجدت نفسك تكتب أكثر من صفحة، ففكر في إضافة روابط إلى المواصفات التقنية المفصلة.
- أنشئها بشكل استباقي: ناقش ADR في اجتماع التصميم الخاص بك، ثم اكتب مسودة له. لا تتركه لما بعد الحدث.
- راجعها: تعامل مع سجلات ADRs كما تتعامل مع الكود. راجع طلبات السحب (Pull Requests) التي تعدلها.
- اربطها: إذا كان ADR جديدًا يحل محل ADR قديم، فقم بربط الاثنين بوضوح بحيث يكون التسلسل التاريخي واضحًا.
الخاتمة
يعد تنفيذ سجلات ADRs ممارسة قليلة الجهد وعالية العائد. فهي تحول هندسة البرمجيات من صندوق أسود إلى تخصص شفاف وقابل للتعلم. من خلال التقاط السياق والأساس المنطقي لقراراتك، تبني قاعدة معرفية مرنة تمكّن فريقك من اتخاذ قرارات أفضل اليوم وفهم نظامك غدًا. ابدأ صغيرًا: اختر قرارًا رئيسيًا حديثًا واكتب ADR له اليوم.