ابدأ باستخدام FastAPI

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

سواء كنت تُنشئ واجهة برمجة تطبيقات REST بسيطة أو خدمة خلفية معقدة، فإن فهم الميزات الأساسية لـ FastAPI سيساعدك على اتخاذ قرار مدروس بشأن اعتمادها في مشاريعك. لتحقيق أقصى استفادة من هذا الدليل، يُنصح بامتلاك معرفة أساسية بدوال بايثون، ومفاهيم HTTP، ومعالجة JSON.

تثبيت FastAPI بالطريقة الصحيحة

يُرسي تثبيت FastAPI بشكل صحيح الأساس لتجربة تطوير سلسة. على عكس العديد من حزم بايثون التي يُمكن تثبيتها باستخدام الأمر pip install ، فقد تطورت آلية تثبيت FastAPI لتوفير وظائف جاهزة للاستخدام بشكل أفضل. سيساعدك فهم خيارات التثبيت هذه على توفير الوقت وتجنب مشاكل التكوين الشائعة.

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

الطريقة المُوصى بها لتثبيت FastAPI هي باستخدام التبعيات الإضافية القياسية. هذا يضمن حصولك على جميع الأدوات التي تحتاجها لتطوير واجهة برمجة التطبيقات (API) دون الحاجة إلى البحث عن حزم إضافية لاحقًا.

$ python -m pip install "fastapi[standard]"

تضمن علامات الاقتباس المحيطة بـ “fastapi[standard]” عمل الأمر بشكل صحيح على مختلف المحطات الطرفية وأنظمة التشغيل. باستخدام الأمر أعلاه، يمكنك تثبيت العديد من الحزم المفيدة، بما في ذلك واجهة سطر الأوامر FastAPI و uvicorn، وهو خادم ASGI لتشغيل تطبيقك.

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

$ python -m pip install fastapi uvicorn

في هذا الدرس، ستستخدم التثبيت [standard] للاستفادة من جميع إمكانيات FastAPI المدمجة. يمكنك التحقق من تثبيتك بالتحقق من إصدار FastAPI في بيئة Python التفاعلية (REPL).

>>> import fastapi
>>> fastapi.__version__
'0.116.1'

بعد تثبيت FastAPI بشكل صحيح، أنت جاهز لإنشاء أول تطبيق ويب API خاص بك. الخطوة التالية هي بناء مثال بسيط يوضح الإمكانيات الأساسية لـ FastAPI.

أنشئ تطبيق FastAPI الأكثر بساطة

لا يتطلب إنشاء تطبيق FastAPI أساسي سوى بضعة أسطر من التعليمات البرمجية. ستبدأ بمثال “مرحباً بالعالم!” البسيط الذي يوضح منهجية إطار العمل في بناء واجهات برمجة التطبيقات (APIs).

يمكنك تسمية ملف FastAPI الرئيسي كما تشاء. من الأسماء الشائعة: app.py، api.py، أو main.py. للمتابعة، أنشئ ملفًا باسم main.py.

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
    return {"message": "Hello, FastAPI!"}

يعرض هذا التطبيق البسيط المفاهيم الأساسية لـ FastAPI. تقوم باستيراد فئة FastAPI، وإنشاء مثيل للتطبيق باسم app، وتحديد نقطة نهاية واحدة تستجيب لطلبات HTTP GET في المسار الجذر عن طريق تعديل دالة ()home.

يمكن أن تكون دوال FastAPI متزامنة أو غير متزامنة. يتعامل الإطار تلقائيًا مع كلا النوعين، مما يمنحك مرونة في كيفية كتابة منطق تطبيقك.

عندما يزور أحد المستخدمين نقطة النهاية الرئيسية لواجهة برمجة التطبيقات (API) الخاصة بك، سيقوم FastAPI بتنفيذ الدالة ()home. تُعيد هذه الدالة قاموسًا. إذا قمتَ بإرجاع قاموس باستخدام FastAPI، فسيتم تحويله تلقائيًا إلى JSON.

لتشغيل تطبيقك، استخدم أمر fastapi الذي توفره واجهة سطر الأوامر FastAPI CLI:

$ fastapi dev main.py

تؤدي إضافة dev إلى أمر fastapi إلى بدء تشغيل تطبيقك في وضع التطوير، مما يتسبب في إعادة تحميل تطبيقك تلقائيًا كلما قمت بتحرير شفرة المصدر الخاصة به.

إذا سمّيت ملف تطبيق FastAPI الرئيسي لديك app.py أو api.py أو main.py، فلن تحتاج حتى إلى تحديد مسار الملف عند استدعاء fastapi dev. ولكن من الأفضل أيضاً، كما تنصّ عليه فلسفة بايثون، أن تكون واضحاً حتى تعرف بالضبط أي ملف يجب تشغيله.

يمكنك إضافة المعاملين –host أو port– لتحديد المضيف والمنفذ اللذين ترغب في تشغيل تطبيق FastAPI عليهما. يبدأ تشغيل تطبيقك افتراضيًا على الرابط http://127.0.0.1:8000. عند زيارة هذا الرابط في متصفحك، ستظهر لك استجابة JSON التالية:

عند تطوير واجهات برمجة التطبيقات (APIs)، يُنصح بإضافة إضافة لتنسيق JSON، مثل إضافة JSONLint، إلى متصفحك. ولمزيد من التحكم، يمكنك استخدام أدوات استكشاف واجهات برمجة التطبيقات مثل Postman أو Bruno للتفاعل مع نقاط النهاية.

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

قم بتعزيز نظامك الخلفي باستخدام FastAPI

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

تسهل FastAPI إنشاء أنماط واجهة برمجة التطبيقات الشائعة هذه باستخدام معلمات المسار ومعلمات الاستعلام ونصوص الطلبات.

لتجربة ذلك، استبدل الكود الموجود في ملف main.py بمثال يوضح ثلاث نقاط نهاية API نموذجية قد تقوم بإنشائها لنظام فهرسة الكتب:

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

books = [
    {"id": 1, "title": "Python Basics", "author": "Real P.", "pages": 635},
    {"id": 2, "title": "Breaking the Rules", "author": "Stephen G.", "pages": 99},
]

class Book(BaseModel):
    title: str
    author: str
    pages: int

@app.get("/books")
def get_books(limit: int | None = None):
    """Get all books, optionally limited by count."""
    if limit:
        return {"books": books[:limit]}
    return {"books": books}

@app.get("/books/{book_id}")
def get_book(book_id: int):
    """Get a specific book by ID."""
    for book in books:
        if book["id"] == book_id:
            return book
    return {"error": "Book not found"}

@app.post("/books")
def create_book(book: Book):
    """Create a new book entry."""
    new_book = {
        "id": len(books) + 1,
        "title": book.title,
        "author": book.author,
        "pages": book.pages
    }
    books.append(new_book)
    return new_book

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

يقبل تعريف الدالة في السطر 16 لنقطة النهاية books/ مُعامل استعلام اختياري يُسمى limit للتحكم في عدد الكتب المطلوب إرجاعها. الأمر متروك لمستخدم واجهة برمجة التطبيقات (API) الخاصة بك لتحديد ما إذا كان يرغب في تحديد عدد الكتب المُسترجعة أو استلام جميع الكتب المتوفرة لديك.

@app.get("/books")
def get_books(limit: int | None = None):
    """Get all books, optionally limited by count."""
    if limit:
        return {"books": books[:limit]}
    return {"books": books}

في السطر 23، تُعرّف نقطة نهاية مع مُعامل المسار {book_id}. يجب على المستخدم توفير هذا المُعامل لتحديد كتاب مُعين بواسطة مُعرّفه. إذا كان الكتاب موجودًا، تُعيد بيانات الكتاب. وإلا، تُرسل رسالة خطأ.

@app.get("/books/{book_id}")
def get_book(book_id: int):
    """Get a specific book by ID."""
    for book in books:
        if book["id"] == book_id:
            return book
    return {"error": "Book not found"}

حتى الآن، قمتَ بتعريف نقاط نهاية تستمع لطلبات GET. في السطر 31، قمتَ بتزيين دالة ()create_book باستخدام ()app.post@. لاحظ كيف أن نقطة النهاية هي نفس مسار books/ كما في السابق. ولكن الآن، قمتَ بتجهيز نقطة النهاية books/ لقبول طلبات POST أيضًا مع نص طلب JSON يحتوي على بيانات الكتاب.

@app.post("/books")
def create_book(book: Book):
    """Create a new book entry."""
    new_book = {
        "id": len(books) + 1,
        "title": book.title,
        "author": book.author,
        "pages": book.pages
    }
    books.append(new_book)
    return new_book

يقوم FastAPI تلقائيًا بالتحقق من صحة بيانات الكتاب الواردة باستخدام نموذج الكتاب الذي قمت بتعريفه في السطر 11، والذي يرث من BaseModel الخاص بـ Pydantic:

class Book(BaseModel):
    title: str
    author: str
    pages: int

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

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

$ fastapi dev main.py

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

• http://127.0.0.1:8000/books
• http://127.0.0.1:8000/books?limit=1
• http://127.0.0.1:8000/books/2

حالياً، يمكنك فقط استرجاع المحتوى المُحدد مسبقاً في ملف main.py عن طريق إرسال طلبات GET من متصفحك. لبدء إضافة بيانات إلى قائمة كتبك، تابع القراءة للتعرف على التوثيق التفاعلي لـ FastAPI.

استفد من التوثيق التلقائي الذي توفره واجهة برمجة التطبيقات السريعة (FastAPI)

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

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

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

تُعدّ واجهة Swagger مفيدةً للغاية عند الرغبة في تجربة طلبات POST، مثل إضافة كتاب جديد إلى قائمتك. أولًا، وسّع نقطة نهاية “إنشاء كتاب”، ثم انقر على زر “جرّبها”، وأضف بيانات كتابك، ثم انقر على “تنفيذ” لإجراء استدعاء واجهة برمجة التطبيقات (API).

إذا لم تكن صفحة توثيق واحدة كافية بالنسبة لك، فيمكنك زيارة http://127.0.0.1:8000/redoc للاطلاع على وثائق بديلة:

يُقدّم ReDoc نفس المعلومات بتنسيق مختلف. يوفر كل من Swagger وReDoc توثيقًا مُولّدًا تلقائيًا لواجهة برمجة التطبيقات (API). عند إضافة نقاط نهاية جديدة أو تغيير نقاط نهاية موجودة، يتم تحديث توثيق واجهة برمجة التطبيقات (API) فورًا بعد إعادة تشغيل الخادم.

يوفر هذا النظام التلقائي لإنشاء الوثائق العديد من المزايا:

• تسهيل انضمام المطورين الجدد: يمكن لأعضاء الفريق الجدد فهم واجهة برمجة التطبيقات (API) الخاصة بك دون الحاجة إلى شرح مطول. تعمل الوثائق التفاعلية كمرجع وأداة اختبار في آن واحد.
• تكامل العميل: يمكن لمطوري الواجهة الأمامية ومستخدمي واجهة برمجة التطبيقات استكشاف نقاط النهاية وتجربة سيناريوهات مختلفة دون كتابة التعليمات البرمجية.
• الصيانة: تبقى الوثائق متزامنة مع التعليمات البرمجية لأنها مُنشأة من نفس المصدر. لا يمكنك نسيان تحديث الوثائق عند تغيير أي وظيفة.

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

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

بفضل بساطته وأدائه وميزاته المدمجة، يُعد FastAPI خيارًا ممتازًا لواجهات برمجة تطبيقات بايثون الحديثة. يوفر التحقق التلقائي من خلال نماذج Pydantic عناء كتابة التعليمات البرمجية المتكررة، بينما تساعد الوثائق التفاعلية مستخدمي واجهة برمجة التطبيقات على فهم نقاط النهاية واختبارها بسهولة.