كيفية تمرير المعلمات في FastAPI

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

حسنًا، مع إنجاز ذلك، دعنا نغوص في عالم FastAPI المثير وتمريرة المعلمات.

ما هي FastAPI؟

FastAPI إطار عمل ويب حديث وسريع (عالي الأداء) لبناء واجهات برمجة التطبيقات باستخدام Python 3.7+ استنادًا إلى تلميحات النوع القياسية في Python. تم تصميمه ليكون سهل الاستخدام والتعلم، مع توفير السرعة والأداء لبرمجة الـ async. FastAPI مثالي لبناء تطبيقات عالية الأداء والميكروسيرفيس. كما أنه يتكامل بسلاسة مع الأدوات والمكتبات الحديثة.

لماذا FastAPI؟

تتمتع FastAPI بالعديد من المزايا التي تجعلها الخيار الأول بين المطورين:

1. السرعة: إنها سريعة. في الواقع، إنها واحدة من أسرع إطارات العمل الوب Python المتاحة.
2. سهولة الاستخدام: تم تصميمها لتكون بديهية ومباشرة.
3. التوثيق: توليد تلقائي لوثائق واجهة برمجة التطبيقات التفاعلية باستخدام OpenAPI وJSON Schema.
4. التحقق: توفر التحقق التلقائي من بيانات الطلب.
5. دعم الـ Async: دعم كامل لبرمجة الـ asynchronous.

البدء مع FastAPI

قبل أن نتعمق في تمرير المعلمات، دعنا نتأكد من أنك قد قمت بتثبيت FastAPI وUvicorn (خادم ASGI). يمكنك تثبيتهما باستخدام pip:

pip install fastapi uvicorn

الآن، دعنا ننشئ تطبيق FastAPI بسيط للبدء:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

يمكنك تشغيل هذا التطبيق باستخدام Uvicorn:

uvicorn main:app --reload

افتح متصفحك وانتقل إلى http://127.0.0.1:8000، وسترى {"Hello": "World"}.

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

في FastAPI، يمكنك تمرير المعلمات بعدة طرق. دعنا نستكشف كل طريقة بتفصيل.

معلمات المسار

تستخدم معلمات المسار لالتقاط الأجزاء المتغيرة من مسار URL. على سبيل المثال، إذا كنت تريد التقاط معرف مستخدم من URL، يمكنك القيام بذلك بهذه الطريقة:

@app.get("/users/{user_id}")
def read_user(user_id: int):
    return {"user_id": user_id}

في هذا المثال، user_id هو معلمة مسار. عندما تزور http://127.0.0.1:8000/users/1، سيتم التقاط معلمة user_id وتمريرها إلى دالة read_user.

تلميحات النوع

لاحظ كيف استخدمنا تلميح النوع int لـ user_id. تستخدم FastAPI هذه التلميحات للتحقق من المعلمات الواردة. إذا قمت بتمرير سلسلة نصية بدلاً من عدد صحيح، ستعيد FastAPI رمز الحالة 422 مما يدل على وجود خطأ في التحقق.

معلمات الاستعلام

تستخدم معلمات الاستعلام لتمرير معلمات اختيارية في URL. تأتي بعد ؟ في URL. على سبيل المثال:

@app.get("/items/")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

هنا، item_id هو معلمة استعلام مطلوبة، بينما q اختيارية. يمكنك الوصول إلى هذه النقطة من خلال زيارة http://127.0.0.1:8000/items/?item_id=1&q=search.

معلمات جسم الطلب

تستخدم معلمات جسم الطلب لتمرير بيانات JSON إلى نقطة نهاية API. يمكنك تعريف نموذج Pydantic للتحقق من بيانات JSON الواردة. إليك مثال:

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

@app.post("/items/")
def create_item(item: Item):
    return item

في هذه الحالة، تتوقع دالة create_item كائن JSON يتطابق مع نموذج Item. ستتحقق FastAPI تلقائيًا من بيانات JSON الواردة وتعيد رمز الحالة 422 إذا كانت البيانات غير صالحة.

معلمات الرأس

يمكن الوصول إلى معلمات الرأس باستخدام فئة Header من fastapi. على سبيل المثال:

from fastapi import Header

@app.get("/items/")
def read_item(user_agent: str = Header(None)):
    return {"User-Agent": user_agent}

ستلتقط هذه الدالة رأس User-Agent من الطلب.

معلمات النموذج

تستخدم معلمات النموذج للتعامل مع بيانات النموذج في الطلب. يمكنك استخدام فئة Form لالتقاط بيانات النموذج. إليك مثال:

from fastapi import Form

@app.post("/login/")
def login(username: str = Form(...), password: str = Form(...)):
    return {"username": username}

في هذه الحالة، تتوقع دالة login بيانات نموذج تحتوي على حقول username وpassword.

معلمات الملف

تسمح لك معلمات الملف بالتعامل مع تحميل الملفات. يمكنك استخدام فئة File من fastapi لالتقاط بيانات الملف. إليك مثال:

from fastapi import File, UploadFile

@app.post("/uploadfile/")
async def create_upload_file(file: UploadFile = File(...)):
    return {"filename": file.filename}

في هذا المثال، تتوقع دالة create_upload_file تحميل ملف. ستتعامل FastAPI مع تحميل الملف وتوفر تفاصيل الملف إلى الدالة.

حقن الاعتماديات

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

from fastapi import Depends

def get_token_header():
    return {"Authorization": "Bearer my_token"}

@app.get("/items/")
def read_item(token: dict = Depends(get_token_header)):
    return token

في هذه الحالة، تعتمد دالة read_item على الدالة get_token_header، التي توفر رأس التوكن.

دمج المعلمات

يمكنك دمج أنواع مختلفة من المعلمات في نقطة نهاية واحدة. إليك مثال يستخدم معلمات المسار والاستعلام والجسم:

@app.put("/items/{item_id}")
def update_item(
    item_id: int,
    q: str = None,
    item: Item = Body(...)
):
    return {"item_id": item_id, "q": q, "item": item}

تتوقع هذه الدالة معلمة مسار (item_id)، ومعلمة استعلام (q)، ومعلمة جسم (item).

التعامل مع تحقق المعلمات

تستخدم FastAPI Pydantic للتحقق من البيانات، مما يوفر مجموعة غنية من الميزات لتعريف والتحقق من نماذج البيانات. يمكنك استخدام Pydantic لفرض قيود على معلماتك. على سبيل المثال:

from pydantic import BaseModel, Field

class Item(BaseModel):
    name: str
    description: str = Field(None, max_length=300)
    price: float = Field(..., gt=0)
    tax: float = None

@app.post("/items/")
def create_item(item: Item):
    return item

في هذه الحالة، تحتوي حقل description على قيود على الحد الأقصى للطول، ويجب أن يكون حقل price أكبر من 0.

ميزات المعلمات المتقدمة

يوفر FastAPI عدة ميزات متقدمة للتعامل مع المعلمات، بما في ذلك:

• الأسماء المستعارة: يمكنك استخدام أسماء مستعارة لمعاملاتك.
• النماذج المتداخلة: يمكنك استخدام نماذج Pydantic المتداخلة لهياكل البيانات المعقدة.
• القيم الافتراضية: يمكنك تعيين قيم افتراضية لمعاملاتك.
• التعبيرات العادية: يمكنك استخدام التعبيرات العادية للتحقق من المعلمات.

استخدام الأسماء المستعارة

يمكنك تعريف أسماء مستعارة لمعاملاتك باستخدام فئة Field من Pydantic. على سبيل المثال:

class Item(BaseModel):
    name: str = Field(..., alias="itemName")
    description: str = None

@app.post("/items/")
def create_item(item: Item):
    return item

في هذه الحالة، سيتم تخصيص الحقل name كاسم مستعار itemName.

النماذج المتداخلة

يمكنك استخدام نماذج Pydantic المتداخلة للتعامل مع هياكل البيانات المعقدة. على سبيل المثال:

class SubItem(BaseModel):
    name: str
    description: str = None

class Item(BaseModel):
    name: str
    description: str = None
    sub_item: SubItem

@app.post("/items/")
def create_item(item: Item):
    return item

في هذه الحالة، يحتوي نموذج Item على نموذج SubItem متداخل.

القيم الافتراضية

يمكنك تعيين قيم افتراضية لمعاملاتك. على سبيل المثال:

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = 10.0

@app.post("/items/")
def create_item(item: Item):
    return item

في هذه الحالة، يحتوي حقل tax على قيمة افتراضية قدرها 10.0.

التعبيرات العادية

يمكنك استخدام التعبيرات العادية للتحقق من معلماتك. على سبيل المثال:

from pydantic import Field

class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None
    code: str = Field(..., regex="^[A-Z0-9]+$")

@app.post("/items/")
def create_item(item: Item):
    return item

في هذه الحالة، يجب أن يتطابق الحقل code مع التعبير العادي ^[A-Z0-9]+$.

استخدام Apidog مع FastAPI لتمرير المعلمات

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

تبسيط إدارة المعلمات باستخدام Apidog

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

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

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

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

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

مثال: اختبار معلمات المسار والاستعلام باستخدام Apidog

دعنا ننظر إلى مثال حول كيفية استخدام Apidog لاختبار معلمات المسار والاستعلام في نقطة نهاية FastAPI.

افترض أن لديك نقطة نهاية FastAPI التالية:

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "q": q}

لاختبار هذه النقطة النهائية باستخدام Apidog:

إنشاء طلب جديد: افتح Apidog وأنشئ طلبًا جديدًا لنقطة نهاية GET /items/{item_id}.

حدد معلمات المسار وأضف معلمات استعلام: أدخل قيمة لمعلمة المسار item_id. على سبيل المثال، يمكنك استخدام 123. ثم أضف معلمة الاستعلام q بقيمة، مثل search_term.

أرسل الطلب وراقب الاستجابة. سيعرض Apidog البيانات JSON المعادة، موضحًا كيف تم التعامل مع المعلمات بواسطة FastAPI.

تعزيز سير العمل الخاص بك

من خلال دمج Apidog في سير عمل تطوير FastAPI الخاص بك، يمكنك التأكد من أن التعامل مع المعلمات لديك قوي وخالي من الأخطاء. تجعل التكامل السلس لـ Apidog مع ميزات التحقق من المعلمات في FastAPI أداة لا تقدر بثمن لكل من التطوير والاختبار.

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

الخاتمة

تمرير المعلمات في FastAPI سهل، بفضل تصميمها البديهي وميزات التحقق القوية. سواء كنت تتعامل مع معلمات المسار، أو معلمات الاستعلام، أو بيانات JSON المعقدة، فإن FastAPI توفر لك كل ما تحتاجه.

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

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

تمنياتنا لك بالتوفيق في البرمجة!