الحزمة التقنية: لماذا FastAPI + PostgreSQL + Docker

ماذا سنبني

مرحبا بك في TaskFlow — واجهة REST API لإدارة المهام بمستوى إنتاجي. بنهاية هذه الدورة، ستكون قد بنيت واجهة برمجية متكاملة تتعامل مع:

• إدارة المستخدمين — التسجيل، تسجيل الدخول، مصادقة JWT
• المشاريع — إنشاء وإدارة مساحات العمل للمشاريع
• المهام — عمليات CRUD كاملة مع تتبع الحالة والأولويات والتعيينات
• التحكم بالوصول حسب الأدوار — مالكون ومديرون وأعضاء بصلاحيات مختلفة

هذا ليس مشروعا تجريبيا. يستخدم TaskFlow نفس أنماط الهندسة المعمارية التي تجدها في الشركات التي تشحن برمجيات حقيقية.

مسؤولية كل جزء من الحزمة

فهم الحزمة كطبقات من المسؤوليات أسهل بكثير من حفظها كقائمة أسماء حزم. كل طلب يدخل TaskFlow يعبر هذه الحدود بالترتيب، وكل حدّ منها هو المكان الذي يُلتقط فيه صنف معيّن من الأخطاء:

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

أين تعيش أرقام الإصدارات

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

• requirements.txt — يُحلّ عند كل pip install، فأي قيد خاطئ يفشل بصوت مسموع.
• وسوم الصور في Dockerfile وdocker-compose.yml — تُحلّ عند كل بناء.

للإصدارات الحالية ارجع إلى المصدر: FastAPI وSQLAlchemy وAlembic وPydantic وPostgreSQL وRedis وPython وDocker Compose.

عادة تستحق التكوين من الآن: اقرأ سياسة الدعم لا الرقم الأحدث فحسب. صفحة إصدارات PostgreSQL تخبرك بمدة دعم كل إصدار رئيسي، وصفحة إصدارات Python تخبرك متى تتوقف التصحيحات الأمنية. هذه التواريخ هي ما ينبغي أن يقود قرار الترقية، لا الرغبة في الأحدث.

لماذا ليس Django REST Framework؟

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

الخلاصة: اختر DRF عندما يكون المنتج تطبيق Django له واجهة برمجية أيضاً. واختر FastAPI عندما يكون المنتج هو الواجهة البرمجية وتتوقع أن يكون العبء على الإدخال/الإخراج — وهذا بالضبط حال TaskFlow.

هيكل المشروع

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

taskflow/
├── docker-compose.yml          # الخدمات: التطبيق، postgres، redis
├── Dockerfile                  # بناء متعدد المراحل للواجهة البرمجية
├── requirements.txt            # التبعيات المثبتة
├── .env                        # متغيرات البيئة (لا ترفعها أبدا)
├── alembic.ini                 # إعدادات Alembic
├── alembic/                    # سكربتات الترحيل
│   └── versions/
├── app/
│   ├── __init__.py
│   ├── main.py                 # نقطة دخول تطبيق FastAPI
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py           # الإعدادات عبر Pydantic
│   │   ├── database.py         # محرك وجلسة SQLAlchemy
│   │   ├── security.py         # JWT وتجزئة كلمات المرور
│   │   └── redis.py            # اتصال Redis
│   ├── api/
│   │   ├── __init__.py
│   │   ├── deps.py             # حقن التبعيات
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── auth.py         # تسجيل الدخول والتسجيل
│   │       ├── users.py        # نقاط نهاية المستخدمين
│   │       ├── projects.py     # نقاط نهاية المشاريع
│   │       └── tasks.py        # نقاط نهاية المهام
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py             # نموذج SQLAlchemy للمستخدم
│   │   ├── project.py          # نموذج المشروع
│   │   └── task.py             # نموذج المهمة
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── user.py             # مخططات Pydantic للمستخدم
│   │   ├── project.py          # مخططات المشروع
│   │   └── task.py             # مخططات المهمة
│   └── tests/
│       ├── __init__.py
│       ├── conftest.py         # الأدوات المساعدة وقاعدة بيانات الاختبار
│       ├── test_auth.py
│       ├── test_users.py
│       ├── test_projects.py
│       └── test_tasks.py

كل مجلد له مسؤولية واضحة:

• core/ — الإعدادات، اتصالات قاعدة البيانات، أدوات الأمان
• api/ — معالجات المسارات منظمة حسب الإصدار
• models/ — نماذج SQLAlchemy ORM (جداول قاعدة البيانات)
• schemas/ — نماذج Pydantic (التحقق من الطلبات والاستجابات)
• tests/ — مجموعة اختبارات pytest

ماذا ستملك بعد هذه الوحدة

بنهاية المرحلة 1، سيكون لديك:

1. حزمة Docker Compose عاملة مع FastAPI وPostgreSQL وRedis
2. نقطة نهاية فحص الصحة في GET /health تؤكد أن جميع الخدمات متصلة
3. هيكل مشروع نظيف جاهز لنماذج قاعدة البيانات ونظام المصادقة ومسارات الواجهة البرمجية التي سنبنيها في الوحدات التالية
4. تبعيات مثبتة حتى تكون بيئتك قابلة للتكرار في أي مكان

انتبه لأمر واحد في المعمل: ملف التبعيات قد يتناقض مع نفسه حتى لو كان كل سطر فيه يسمّي حزمة حقيقية وحديثة. الشيء الوحيد الذي يكشف ذلك هو pip install. شغّله قبل أن تكتب سطراً واحداً من كود التطبيق.

التالي: معمل تطبيقي — تهيئة مشروع TaskFlow :::