استخدام SQLAlchemy لبناء طبقة ORM في Python

تسمح ORM للمطور بالتعامل مع الجداول عبر كائنات Python، لكنها لا تلغي الحاجة إلى فهم SQL والعلاقات. SQLAlchemy يقدم نمطاً مرناً لبناء النماذج وتنفيذ الاستعلامات، ويمكن استخدامه مع SQLite أو قواعد أخرى. سنعرف نموذج User ونسجل مستخدماً ثم نقرأه باستعلام. التركيز هنا على الجلسة، والالتزام بالتغييرات، وإغلاق الموارد، لأن الأخطاء في هذه النقاط تسبب بيانات غير محفوظة أو اتصالات معلقة.

الفكرة الأساسية

يمثل model جدولاً، ويمثل كل instance صفاً جديداً أو موجوداً. يتتبع Session التغييرات ثم يرسلها إلى قاعدة البيانات عند commit. إذا فشل جزء من العملية، نستخدم rollback حتى لا تبقى الجلسة في حالة غير صالحة. يجب تصميم العلاقات والقيود في النموذج، لكن لا تعتمد على Python وحدها؛ القاعدة نفسها ينبغي أن تفرض القيود عندما يكون ذلك ممكناً.

مثال برمجي عملي

from sqlalchemy import create_engine, String, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(80))

engine = create_engine("sqlite:///app.db")
Base.metadata.create_all(engine)

with Session(engine) as session:
    session.add(User(name="سارة"))
    session.commit()
    users = session.scalars(select(User)).all()
    print([user.name for user in users])

شرح المثال

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

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

ابدأ من عقد واضح

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

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

تجارب ينبغي ألا تهملها

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

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

ما الذي يجعل الحل عملياً؟

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

خطوة ما بعد المثال

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

أخطاء ينبغي تجنبها

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

خطوة تالية مناسبة

أضف جدولاً للمهام مرتبطاً بالمستخدم، ثم جرّب علاقة one-to-many. اكتب اختباراً ينشئ قاعدة مؤقتة، وينفذ الاستعلام، ثم يحذفها بعد النهاية حتى لا تعتمد الاختبارات على ملف محلي قديم.

ما الذي تخفيه ORM

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

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

خطة تطبيق عملية

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

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

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

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

الخلاصة

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

تعديل المقال

Evlune

استخدام SQLAlchemy لبناء طبقة ORM في Python