محتويات الدورة

FastAPI / الأساسي: HTTP والحدود ذات الأنواع / الدرس 3

أجسام الطلب والتحقق بـPydantic

حول JSON إلى أمر ضيق متحقق منه مع فصل التحليل والتحويل وقيود الحقول والقواعد المشتركة.

وقت القراءة التقريبي: 3 دقيقةتاريخ مراجعة المحتوى
في هذه الصفحة

أهداف الدرس

  • اشرح افتراضات وحدود موضوع «أجسام الطلب والتحقق بـPydantic».
  • فسر المثالين الكاملين وعلل المخرجات الملاحظة.
  • شخص الإخفاقات وطبق الحلول المشروحة مع وضوح ملكية الهوية والحالة ودورة الحياة.

يحدد النموذج حدا لا قاعدة بيانات

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

معرفة موضع التحويل في العقد

تجري Pydantic تحويلات مدعومة كنص عددي لعدد، لا قبول كل قيمة أوصرامة الجميع. استخدم الصارم حين يلزم واختبر مدخل JSON وPython المعنيين. يحول المثال النص ويفحص الإيجابية؛ فقرر ملاءمته للعقد ولا تعمم فائدته أومنعه. افصل الغائب وnull والفارغ والنوع الخاطئ.

python فحص جسم وحقل مجهول كامل
from fastapi import FastAPI
from fastapi.testclient import TestClient
from pydantic import BaseModel, ConfigDict, Field
class Item(BaseModel):
    model_config = ConfigDict(extra="forbid")
    name: str
    quantity: int = Field(gt=0)
app = FastAPI()
@app.post("/items")
def create(item: Item): return item.model_dump()
with TestClient(app) as client:
    print(client.post("/items", json={"name": "pen", "quantity": "2"}).json())
    print(client.post("/items", json={"name": "pen", "quantity": 2, "admin": True}).status_code)
الناتج المتوقع
{'name': 'pen', 'quantity': 2}
422

ينتج التحويل العدد 2 ويرفض admin المجهول 422 قبل عبور الحد.

التحقق من العلاقات صراحة

لا يعبر حد منفرد عن كل علاقة؛ فقد يلزم تجاوز end لـstart. يعبر model validator ويعيد النسخة. يجمع المثال أعدادا صارمة وترتيبا ويطبع نوع خطأ مستقرا. لا تجعل التحقق يجلب قاعدة أويرسل أويغير عاما خفية؛ فقد يعمل بسياقات متعددة ولا ينبغي أن يغير المرفوض العالم جزئيا.

python تحقق صارم ومشترك كامل
from pydantic import BaseModel, ConfigDict, ValidationError, model_validator
class Window(BaseModel):
    model_config = ConfigDict(strict=True)
    start: int
    end: int
    @model_validator(mode="after")
    def ordered(self):
        if self.end <= self.start:
            raise ValueError("end must exceed start")
        return self
print(Window(start=1, end=3).model_dump())
try:
    Window(start=3, end=1)
except ValidationError as error:
    print(error.errors()[0]["type"])
try:
    Window(start="1", end=3)
except ValidationError as error:
    print(error.errors()[0]["type"])
الناتج المتوقع
{'start': 1, 'end': 3}
value_error
int_type

ينجح الترتيب ويعطي عكسه value_error والنص الصارم int_type دون أثر خارجي.

جعل التسلسل والمخطط مقصودين

تستخدم v2 عمليات model_dump وmodel_validate، وتحتاج أمثلة قديمة انتقالا لا نسخا أعمى. تختلف تمثيلات Python وJSON للتاريخ والعشري؛ فاختر النمط. تؤثر البدائل والمجهول بالعقد ولا يثبت المخطط الإذن أوحد البايت والتزامن. راجع المخطط والطلب معا بعد التحديث أونمط النموذج.

جعل الخطأ مفيدا وآمنا

تعيد FastAPI خطأ الطلب قبل المعالج لغير الصالح عادة. اختبر الحالة والموقع والنوع لا تسجل الجسم كاملا. يختلف فشل المجال بعد التحليل. تستخدم الأمثلة بيانات اصطناعية وعميلا أواستدعاء محليا بلا قاعدة أوشبكة أوهوية. غط الشكل والمجهول وnull والحد والصرامة والعلاقة بعقد مفهوم لا زخارف مجهولة.

الأخطاء الشائعة وإصلاحها

تصبح حقول العميل خصائص داخلية

لماذا يحدث؟
نسخ الجسم دون نموذج ضيق.
كيف تصلحه؟
تحقق بقائمة وابن الداخل بوعي.
كيف تتجنب تكراره؟
اختبر حقول الامتياز والمجهول.

يقبل النص العددي خلاف المتوقع

لماذا يحدث؟
اختلط التحويل بالصرامة.
كيف تصلحه؟
اختر واختبر الصرامة.
كيف تتجنب تكراره؟
وثق الصيغ المقبولة.

تجتمع حقول صحيحة بأمر باطل

لماذا يحدث؟
لم يفحص قيد العلاقة.
كيف تصلحه؟
أضف قاعدة نقية بالنموذج أوالمجال.
كيف تتجنب تكراره؟
اختبر التركيبات لا الحقول فقط.

اختبر فهمك

1. يسمح النموذج بعددين موجبين. هل يثبت ترتيب النهاية؟

اعرض الحل المشروح

لا؛ افحص العلاقة وحالات المساواة والعكس والصحة دون حفظ أوأثر كي لا يترك الرفض تغييرا جزئيا.

2. لماذا يستبعد الطلب is_admin الداخلية؟

اعرض الحل المشروح

لا يختار العميل امتيازه بحقل صحيح شكلا؛ احفظ القرار بحالة موثوقة ونموذج مدخل للبيانات المسموحة فقط.

أهم ما تعلمته

  • تصرح BaseModel بالحقول والتحقق، وتستخدمها FastAPI للتحليل والخطأ والمخطط دون حفظ أوإذن أومعاملة.
  • لا يعبر حد منفرد عن كل علاقة؛ فقد يلزم تجاوز end لـstart.
  • تعيد FastAPI خطأ الطلب قبل المعالج لغير الصالح عادة.

المراجع الرسمية