تثبيت FastAPI وإنشاء أول endpoint

الدرس 12: تثبيت FastAPI وإنشاء أول Endpoint

مرحباً بك في أول درس عملي في عالم FastAPI! بعد أن تعرفت في الدرس السابق على أساسيات HTTP و REST API، حان الوقت الآن لتطبيق ذلك عملياً. في هذا الدرس، سنقوم بتثبيت FastAPI على جهازك، ثم نكتب أول كود لإنشاء نقطة نهاية (endpoint) بسيطة ترسل لك رسالة ترحيب. ستشعر بالإنجاز عندما ترى أول API يعمل أمام عينيك.

ما هو FastAPI؟

FastAPI هو إطار عمل (Framework) حديث وسريع لبناء APIs باستخدام لغة بايثون. يتميز بسهولة الاستخدام، والأداء العالي، والتوثيق التلقائي. إذا كنت مبتدئاً، فFastAPI هو الخيار الأمثل لك لأنه يسمح لك ببناء تطبيقات قوية بكتابة كود قليل وواضح.

لماذا نحتاج إلى تثبيت FastAPI؟

قبل أن نتمكن من استخدام FastAPI، يجب أن يكون مثبتاً في بيئة بايثون الخاصة بنا. التثبيت يضيف مكتبة FastAPI ومكتبة مساعدة تسمى uvicorn (التي تعمل كخادم لتشغيل التطبيق). بدون التثبيت، لن يتمكن بايثون من فهم أوامر FastAPI.

خطوات التنفيذ

سنقسم العملية إلى ثلاث خطوات رئيسية: التثبيت، كتابة الكود، وتشغيل الخادم.

الخطوة 1: تثبيت FastAPI و Uvicorn

افتح الطرفية (Terminal) أو موجه الأوامر (Command Prompt) وتأكد من أنك داخل البيئة الافتراضية التي أنشأتها في الدرس السابق (إن وجدت). ثم اكتب الأمر التالي:

pip install fastapi uvicorn

سيقوم هذا الأمر بتحميل وتثبيت أحدث إصدار من FastAPI و Uvicorn. انتظر حتى يكتمل التثبيت. ستظهر رسالة تؤكد نجاح التثبيت.

الخطوة 2: إنشاء ملف بايثون وكتابة أول Endpoint

الآن، قم بإنشاء ملف جديد باسم main.py في أي مجلد تريده. افتح الملف في محرر النصوص المفضل لديك (مثل VS Code) واكتب الكود التالي:

from fastapi import FastAPI

# إنشاء تطبيق FastAPI
app = FastAPI()

# تعريف أول endpoint
@app.get("/")
def read_root():
    return {"message": "مرحباً بك في أول API لي!"}

شرح الكود:

• from fastapi import FastAPI: نستورد مكتبة FastAPI.
• app = FastAPI(): ننشئ كائن (instance) من التطبيق. هذا الكائن هو قلب API الخاص بنا.
• @app.get("/"): هذا ما يسمى بـ "decorator". يخبر FastAPI أن الدالة التالية ستستجيب لطلبات HTTP من نوع GET على المسار الرئيسي /.
• def read_root(): الدالة التي سيتم تنفيذها عند زيارة المسار /. يمكن تسميتها أي اسم تريده.
• return {"message": "..."}: الدالة ترجع قاموس (dictionary) بايثون. FastAPI يقوم تلقائياً بتحويله إلى JSON ليرسله كاستجابة.

الخطوة 3: تشغيل الخادم واختبار الـ Endpoint

ارجع إلى الطرفية، وتأكد من أنك في نفس المجلد الذي يحتوي على ملف main.py. ثم اكتب الأمر التالي:

uvicorn main:app --reload

شرح الأمر:

• uvicorn: اسم الخادم الذي سنستخدمه.
• main:app: main هو اسم ملف بايثون (بدون .py)، و app هو اسم كائن FastAPI الذي أنشأناه داخل الملف.
• --reload: خيار رائع للمبتدئين. يجعل الخادم يعيد التشغيل تلقائياً كلما قمت بتعديل وحفظ الكود. هذا يوفر عليك عناء إيقاف وتشغيل الخادم يدوياً في كل مرة.

بعد تشغيل الأمر، ستظهر رسالة في الطرفية تخبرك بأن الخادم يعمل على http://127.0.0.1:8000. افتح متصفح الإنترنت واذهب إلى هذا الرابط. يجب أن ترى رسالة JSON التالية:

{"message": "مرحباً بك في أول API لي!"}

تهانينا! لقد أنشأت أول API لك بنجاح.

أخطاء شائعة وكيفية تجنبها

• خطأ في اسم الملف: تأكد من أن اسم ملف بايثون هو main.py وأنك تستخدمه بشكل صحيح في الأمر uvicorn main:app.
• نسيان تفعيل البيئة الافتراضية: إذا كنت تستخدم بيئة افتراضية، فتأكد من تفعيلها قبل تشغيل أي أمر. ستلاحظ ظهور اسم البيئة في بداية سطر الطرفية.
• استخدام port مشغول: إذا كان المنفذ 8000 مستخدماً من قبل تطبيق آخر، يمكنك تغييره باستخدام الأمر uvicorn main:app --reload --port 8001.
• عدم حفظ الملف: تذكر دائماً حفظ ملف main.py بعد كل تعديل. مع خيار --reload، سيلاحظ الخادم التغييرات تلقائياً.

مثال إضافي: إنشاء Endpoint يرحب بك شخصياً

لنقم بتوسعة الكود قليلاً. أضف endpoint جديد يستقبل اسمك في الرابط ويرسل لك رسالة ترحيب مخصصة. عدّل ملف main.py ليصبح هكذا:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"message": "مرحباً بك في أول API لي!"}

@app.get("/greet/{name}")
def greet_user(name: str):
    return {"message": f"أهلاً بك يا {name}!"}

الآن، احفظ الملف. لاحظ أن الخادم سيعيد التشغيل تلقائياً. اذهب في المتصفح إلى http://127.0.0.1:8000/greet/Ahmed. سترى رسالة ترحيب باسم "Ahmed". جرب تغيير الاسم في الرابط لترى النتيجة.

شرح الكود الجديد:

• @app.get("/greet/{name}"): نستخدم {name} كمتغير في المسار. هذا يسمى "path parameter".
• def greet_user(name: str): الدالة تستقبل متغير name من نوع نصي (str). FastAPI يقوم تلقائياً باستخراج القيمة من الرابط وتمريرها إلى الدالة.
• f"أهلاً بك يا {name}!": نستخدم f-string لدمج المتغير داخل النص.

تمرين صغير

حان دورك للتطبيق! قم بالتالي:

1. أضف endpoint جديد في ملف main.py على المسار /about.
2. يجب أن يعيد هذا endpoint قاموساً يحتوي على مفتاح app_name بقيمة "My First API" ومفتاح version بقيمة "1.0.0".
3. اختبره في المتصفح على الرابط http://127.0.0.1:8000/about.

إذا نجحت، فأنت الآن قادر على إنشاء endpoints بسيطة باستخدام FastAPI. في الدرس القادم، سنتعمق أكثر في التعامل مع المعاملات (parameters) المختلفة.