لقد تم طرح إحدى الميزات الأكثر توقعًا لـ FastAPI منذ ثلاثة أسابيع تقريبًا. على الأقل عندما نتحدث عن Pydantic Models FastAPI.

نعم، أنا أتحدث عن القدرة على استخدام نماذج Pydantic لتعيين معلمات الاستعلام الخاصة بك.

لذلك في هذا المنشور، سأحاول أن أظهر لك كل شيء؟ يمكن و ؟ لا أستطيع أن أفعل حيال هذا الموضوع؟:

؟ تعيين معلمات الاستعلام

أول شيء عليك القيام به لبدء تعيين معلمات الاستعلام الخاصة بك باستخدام Pydantic هو التأكد من أنك تستخدم FastAPI الإصدار 0.115.0.

بعد ذلك، يمكنك دائمًا الانتقال إلى مستندات FastAPI للتحقق مما هو متاح بالفعل. يقوم سيباستيان وأعضاء الفريق بعمل جيد حقًا في الحفاظ على تحديث المستندات وتزويدها بالمعلومات ✨.

؟ قليلا من التاريخ

لنبدأ ببعض الأمثلة حول كيفية استخدامنا لتعيين معلمات الاستعلام في FastAPI. ?

أبسط طريقة للقيام بذلك هي:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def search(
    limit: int | None = 10,
    skip: int | None = 1,
    filter: str | None = None
):
    return {
        "limit": limit,
        "skip": skip,
        "filter": filter
    }

والآن يمكنك ببساطة الاتصال على:

GET http://localhost:8000/?limit=42&skip=12&filter=banana

ولكن إذا حددنا أنه سيتم استخدام معلمات الاستعلام هذه في مسارات أخرى، فسنعزلها بشيء مثل:

from typing import Any
from fastapi import Depends, FastAPI, Query

app = FastAPI()

async def pagination_query_string(
    limit: int | None = Query(10, ge=5, le=100),
    skip: int | None = Query(1, ge=1),
    filter: str | None = Query(None)
) -> dict[str, Any]:
    return {
        "limit": limit,
        "skip": skip,
        "filter": filter
    }

@app.get("/")
async def search(q: dict[str, Any] = Depends(pagination_query_string)):
    return q

أو بما أننا نستخدم Pydantic لتعيين نماذجنا، فسنحصل على القليل من إعادة البناء:

from fastapi import Depends, FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class PaginationQueryString(BaseModel):
    limit: int | None = 10
    skip: int | None = 1
    filter: str | None = None

async def pagination_query_string(
    limit: int | None = Query(10, ge=5, le=100),
    skip: int | None = Query(1, ge=1),
    filter: str | None = Query(None)
) -> PaginationQueryString:
    return PaginationQueryString(
        limit=limit,
        skip=skip,
        filter=filter
    )

@app.get("/")
async def search(q: PaginationQueryString = Depends(pagination_query_string)):
    return q

⌨️ استخدام Pydantic لتعيين سلاسل الاستعلام

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

from typing import Annotated
from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class PaginationQueryString(BaseModel):
    limit: int | None = 10
    skip: int | None = 1
    filter: str | None = None

@app.get("/")
async def search(q: Annotated[PaginationQueryString, Query()]):
    return q

سهل، أليس كذلك؟ ?

⚠️ ما هي القيود؟

على الأقل في الإصدار 0.115.0، لا يعمل بشكل جيد مع النماذج المتداخلة.

لنجرب شيئًا مثل:

from typing import Annotated
from fastapi import FastAPI, Query
from pydantic import BaseModel

app = FastAPI()

class Filter(BaseModel):
    name: str | None = None
    age: int | None = None
    nickname: str | None = None

class PaginationQueryString(BaseModel):
    limit: int | None = 10
    skip: int | None = 1
    filter: Filter | None = None

@app.get("/")
async def search(q: Annotated[PaginationQueryString, Query()]):
    return q

إذا سميناها كما قبل:

GET http://localhost:8000/?limit=42&skip=12&filter=chocolate

سنحصل على خطأ يخبرنا أن الفلتر هو كائن:

{
    "detail": [
        {
            "type": "model_attributes_type",
            "loc": [
                "query",
                "filter"
            ],
            "msg": "Input should be a valid dictionary or object to extract fields from",
            "input": "chocolate"
        }
    ]
}

على الأقل الآن، هذا صحيح تمامًا! لقد قمنا بتغيير مرشحنا ليكون نموذج Pydantic، وليس سلسلة. لكن إذا حاولنا تحويله إلى قاموس:

http://localhost:8000/?limit=42&skip=12&filter={"name": "Rafael", "age": 38, "nickname": "ceb10n"}

سيخبرنا FastAPI أن الفلتر يجب أن يكون قاموسًا صالحًا؟:

{
    "detail": [
        {
            "type": "model_attributes_type",
            "loc": [
                "query",
                "filter"
            ],
            "msg": "Input should be a valid dictionary or object to extract fields from",
            "input": "{\"name\": \"Rafael\", \"age\": 38, \"nickname\": \"ceb10n\"}"
        }
    ]
}

يحدث هذا لأن FastAPI سيعتمد على QueryParams الخاصة بـ Starlette، والتي ستعطي سلسلة لـ FastAPI، وليس إملاء. وعلى الأقل في الإصدار 0.115.0، سيعطيك هذا خطأ.

⁉️ إذن متى أستخدم نماذج Pydantic مع معلمات الاستعلام الخاصة بي؟

الأمر بسيط جدًا:

✅ هل لديك سلاسل استعلام بسيطة لا تحتاج إلى أي كائنات متداخلة معقدة؟ استخدمه! ?

❌ هل قمت بإنشاء سلسلة استعلام متداخلة ومعقدة؟ لا تستخدمه بعد؟. (وربما عليك أن تحاول إعادة التفكير في سلاسل الاستعلام الخاصة بك. كلما كان الأمر أبسط، كلما كان ذلك أفضل؟)