كل ما تحتاج لمعرفته حول معلمات استعلام FastAPI (مع أفضل الممارسات)

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

لماذا تستخدم معاملات استعلام FastAPI؟

1. المرونة: تتيح معاملات استعلام FastAPI للعملاء تخصيص نتائج طلباتهم. على سبيل المثال، يمكن للمستخدمين تصفية نتائج البحث استنادًا إلى معايير محددة مثل الفئة أو السعر أو التقييم.
2. سهولة الاستخدام: تعمل على تبسيط التفاعل بين العملاء وواجهة برمجة التطبيقات. يمكن للعملاء بسهولة إضافة معاملات استعلام إلى عنوان URL، بينما يمكن للمطورين التحقق بسرعة من هذه المعاملات ومعالجتها في الشيفرة الخاصة بهم.
3. الأداء: من خلال استخدام معاملات استعلام FastAPI، يمكنك تقليل عدد النقاط النهائية المطلوبة لواجهة برمجة التطبيقات. بدلاً من إنشاء نقاط نهائية منفصلة لكل خيار تصفية، يمكن لنقطة نهائية واحدة التعامل مع عدة معاملات استعلام.

كيفية استخدام معاملات استعلام FastAPI

تعريف معاملات استعلام FastAPI

لتعريف معاملات الاستعلام في FastAPI، ما عليك سوى تضمينها كمعاملات دالة في تعريف نقطة النهاية الخاصة بك. إليك مثال أساسي:

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, max_length=50),
    skip: int = Query(default=0, ge=0),
    limit: int = Query(default=10, le=100)
):
    return {"q": q, "skip": skip, "limit": limit}

في هذا المثال:

• q: معلمة سلسلة اختيارية بحد أقصى لطول 50 حرفًا.
• skip: معلمة صحيحة تحدد عدد العناصر التي يجب تخطيها، مع قيمة افتراضية تبلغ 0 وقيمة دنيا تبلغ 0.
• limit: معلمة صحيحة تحدد الحد الأقصى لعدد العناصر التي يجب إرجاعها، مع قيمة افتراضية تبلغ 10 وقيمة قصوى تبلغ 100.

الوصول إلى معاملات استعلام FastAPI

عند قيام عميل بإرسال طلب إلى نقطة النهاية، يقوم FastAPI تلقائيًا باستخراج معاملات الاستعلام من عنوان URL وتمريرها إلى الدالة. على سبيل المثال، إذا تم تقديم طلب إلى /items/?q=foo&skip=10&limit=5، ستتلقى الدالة:

• q = "foo"
• skip = 10
• limit = 5

هذه الاستخراج التلقائي يجعل من السهل العمل مع معاملات استعلام FastAPI دون الحاجة إلى منطق التحليل الإضافي.

معاملات استعلام FastAPI الاختيارية والضرورية

بشكل افتراضي، تكون معاملات استعلام FastAPI اختيارية. إذا لم يتم تقديم معلمة في الطلب، سيستخدم FastAPI القيمة الافتراضية المحددة. لجعل معلمة استعلام إلزامية، ببساطة قم بإزالة القيمة الافتراضية:

@app.get("/items/")
async def read_items(required_param: str):
    return {"required_param": required_param}

إذا لم يتم تضمين required_param في الطلب، سيرجع FastAPI خطأ 422 كيان غير قابل للمعالجة، مما يشير إلى أن معلمة استعلام مطلوبة مفقودة.

التعامل مع قيم متعددة لمعاملات استعلام FastAPI

يسمح FastAPI لك بتعريف معلمة استعلام يمكن أن تقبل قيمًا متعددة. يمكنك القيام بذلك من خلال تحديد نوع المعلمة كقائمة:

from typing import List

@app.get("/items/")
async def read_items(q: List[str] = Query(default=[])):
    return {"q": q}

في هذه الحالة، يمكن للعميل تقديم طلب مثل /items/?q=foo&q=bar&q=baz، وسيتولى FastAPI تحليل القيم إلى قائمة. هذه الميزة مفيدة بشكل خاص للسيناريوهات التي يرغب فيها المستخدمون في تصفية النتائج استنادًا إلى معايير متعددة.

التحقق من صحة معاملات استعلام FastAPI

يوفر FastAPI تحققًا مدمجًا لمعاملات الاستعلام باستخدام دالة Query. يمكنك تحديد القيود مثل القيم الدنيا والعليا، وقيود الطول، وأنماط regex. إليك مثال:

@app.get("/items/")
async def read_items(
    q: str = Query(default=None, min_length=3, max_length=50),
    item_id: int = Query(ge=1, le=100)
):
    return {"q": q, "item_id": item_id}

في هذا المثال، يجب أن تكون q سلسلة بطول أدنى قدره 3 وطول أقصى قدره 50. يجب أن يكون item_id عددًا صحيحًا بين 1 و100. سيتحقق FastAPI تلقائيًا من هذه القيود وسيرجع خطأ إذا لم تلب المدخلات المعايير المحددة.

توليد الوثائق التلقائية مع FastAPI وOpenAPI

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

ما هو OpenAPI؟

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

كيف يقوم FastAPI بتوليد الوثائق

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

• مسارات النقاط النهائية: المسارات التي تحددها في تطبيقك.
• طرق HTTP: الطرق (GET، POST، PUT، DELETE، إلخ) المرتبطة بكل نقطة نهاية.
• المعاملات: كل من معاملات المسار والاستعلام، بما في ذلك أنواعها والقيم الافتراضية والقيود.
• نماذج الاستجابة: تنسيق الاستجابة المتوقع لكل نقطة نهاية.

كيفية الوثائق التفاعلية مع FastAPI

يوفر FastAPI واجهتين وثائقيتين تفاعليتين خارج الصندوق:

1. واجهة Swagger: يمكن الوصول إليها على /docs، تتيح هذه الواجهة للمستخدمين استكشاف نقاط نهاية واجهة برمجة التطبيقات الخاصة بك، عرض تنسيقات الطلب والاستجابة، واختبار النقاط النهائية مباشرة من المتصفح.
2. ReDoc: متاحة على /redoc، توفر هذه الواجهة عرضًا أكثر تفصيلًا وتنظيمًا لوثائق واجهة برمجة التطبيقات الخاصة بك، مما يسهل التنقل وفهم النقاط النهائية المختلفة ومعاملاتها.

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

تعزيز الوثائق لمعلمات الاستعلام

بينما يولد FastAPI وثائق أساسية لمعاملات الاستعلام الخاصة بك، يمكنك تعزيزها أكثر من خلال تقديم أوصاف تفصيلية، أمثلة، وبيانات وصفية إضافية. إليك كيف:

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

from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="مصطلح البحث لتصفية العناصر."),
    skip: int = Query(default=0, ge=0, description="عدد العناصر التي يجب تخطيها."),
    limit: int = Query(default=10, le=100, description="الحد الأقصى لعدد العناصر التي يجب إرجاعها.")
):
    return {"q": q, "skip": skip, "limit": limit}

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

@app.get("/items/")
async def read_items(
    q: str | None = Query(default=None, description="مصطلح البحث لتصفية العناصر.", example="apple"),
    skip: int = Query(default=0, ge=0, description="عدد العناصر التي يجب تخطيها.", example=5),
    limit: int = Query(default=10, le=100, description="الحد الأقصى لعدد العناصر التي يجب إرجاعها.", example=20)
):
    return {"q": q, "skip": skip, "limit": limit}

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

4. تطبيق الأنواع: استخدم تطبيقات أنواع مناسبة لمعاملات الاستعلام الخاصة بك. يستخدم FastAPI هذه التطبيقات لتوليد أنواع البيانات المتوقعة في الوثائق تلقائيًا، مما يساعد المستخدمين على فهم نوع البيانات التي يجب عليهم تقديمها.

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

فوائد الوثائق المحسنة

1. تحسين سهولة الاستخدام: تجعل معاملات الاستعلام الموثقة جيدًا من السهل على المطورين فهم كيفية التفاعل مع واجهة برمجة التطبيقات الخاصة بك. يقلل هذا من منحنى التعلم ويزيد من الاعتماد.
2. تقليل طلبات الدعم: يمكن أن تساعد الوثائق الواضحة في الإجابة على الأسئلة الشائعة وتقليل عدد طلبات الدعم التي تتلقاها من المستخدمين الذين يحاولون فهم كيفية استخدام واجهة برمجة التطبيقات الخاصة بك.
3. تسريع التطوير: يمكن للمطورين أن يرجعوا بسرعة إلى الوثائق أثناء بناء التطبيقات، مما يؤدي إلى دورات تكامل وتطوير أسرع.
4. زيادة اعتماد واجهة برمجة التطبيقات: يمكن أن تجذب الوثائق الشاملة وسهلة الاستخدام المزيد من المطورين لاستخدام واجهة برمجة التطبيقات الخاصة بك، مما يعزز النجاح والوصول العام لها.
5. الاتساق: يضمن التوثيق التلقائي أن تكون وثائق واجهة برمجة التطبيقات الخاصة بك متسقة مع التنفيذ الفعلي، مما يقلل من التباينات التي يمكن أن تؤدي إلى الارتباك.

تقنيات متقدمة لمعاملات استعلام FastAPI

استخدام Enums لمعاملات استعلام FastAPI

يمكنك تقييد معاملات استعلام FastAPI لمجموعة محددة مسبقًا من القيم باستخدام Python Enums. هذه مفيدة للمعاملات التي ينبغي أن تقبل خيارات محددة فقط:

from enum import Enum

class ItemType(str, Enum):
    fruit = "fruit"
    vegetable = "vegetable"
    dairy = "dairy"

@app.get("/items/")
async def read_items(item_type: ItemType):
    return {"item_type": item_type}

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

اعتماديات معاملات الاستعلام

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

from fastapi import Depends

def query_param_dependency(q: str | None = None):
    return q if q else "default"

@app.get("/items/")
async def read_items(q: str = Depends(query_param_dependency)):
    return {"q": q}

في هذا المثال، تتحقق دالة query_param_dependency مما إذا كانت معلمة الاستعلام q قد تم تقديمها. إذا لم تكن، تعيد قيمة افتراضية. يعزز هذا النهج إعادة استخدام الشيفرة ويجعل وظائف نقاط النهاية لديك نظيفة.

التعامل مع الأخطاء لمعاملات استعلام FastAPI

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

from fastapi import HTTPException

@app.get("/items/")
async def read_items(q: str | None = Query(default=None)):
    if q is None:
        raise HTTPException(status_code=400, detail="معلمة الاستعلام 'q' مطلوبة.")
    return {"q": q}

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

اختبار معاملات استعلام FastAPI

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

import httpx
import pytest

@pytest.mark.asyncio
async def test_read_items():
    async with httpx.AsyncClient() as client:
        response = await client.get("http://localhost:8000/items/?q=test&skip=0&limit=10")
        assert response.status_code == 200
        assert response.json() == {"q": "test", "skip": 0, "limit": 10}

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

الخاتمة

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

موارد إضافية حول FastAPI

لتعزيز فهمك لمعاملات استعلام FastAPI، فكر في استكشاف الموارد التالية:

1. وثائق FastAPI: توفر وثائق FastAPI الرسمية معلومات شاملة حول معاملات الاستعلام والميزات الأخرى.
2. مستودع FastAPI على GitHub: تحقق من مستودع FastAPI على GitHub للشيفرة المصدرية والأمثلة ومساهمات المجتمع.
3. دروس FastAPI: ابحث عن دروس ودورات تعليمية عبر الإنترنت تركز على FastAPI لتعميق معرفتك ومهاراتك.

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