كيف تضيف قيود التحقق من الصحة إلى المعاملات؟

Question

Accepted Answer

بعد فحص النوع، يسمح لك FastAPI بإضافة **قيود** إلى معاملات المسار/الاستعلام وحقول النموذج باستخدام `Query` و `Path` و `Field` — فرض قواعد مثل الطول والنطاقات والأنماط، مع أخطاء 422 تلقائية والتوثيق عند الانتهاك. ## قيود Query و Path ```python from fastapi import Query, Path @app.get("/items") def search( q: str = Query(min_length=3, max_length=50), # string length bounds page: int = Query(default=1, ge=1), # >= 1 limit: int = Query(default=10, ge=1, le=100), # 1 <= limit <= 100 code: str = Query(pattern=r"^[A-Z]{3}$"), # regex pattern ): ... @app.get("/items/{item_id}") def get(item_id: int = Path(ge=1)): # path param must be >= 1 ... ``` `Query()` و `Path()` تضيف قيود معاملات الاستعلام والمسار. الشائعة منها: `min_length`/`max_length` (النصوص)، `ge`/`gt`/`le`/`lt` (الأرقام)، `pattern` (regex). الانتهاكات تنتج خطأ واضح 422 تلقائيًا. ## قيود Field على نماذج Pydantic ```python from pydantic import BaseModel, Field, EmailStr class User(BaseModel): name: str = Field(min_length=1, max_length=100) age: int = Field(ge=0, le=120) email: EmailStr # format validation via a type bio: str = Field(default="", max_length=500, description="User bio") ``` تنطبق نفس القيود على حقول النموذج عبر `Field()`، التحقق من أجسام الطلب. أنواع متخصصة (`EmailStr`، `HttpUrl`، `UUID`) تتحقق من التنسيقات. ## القيود تثري الوثائق أيضًا ```python q: str = Query(min_length=3, description="Search query", example="phone") # the constraints + description + example appear in the auto-generated API docs ``` كل قيد تعلنه ينعكس أيضًا في توثيق OpenAPI، حتى يرى المستهلكون القواعد. ## لماذا هذا مهم إضافة قيود التحقق من الصحة مهمة لكل من **الأمان/المتانة** وتصميم API جيد — إعلان القواعد (حدود الطول، نطاقات الأرقام، أنماط regex، أنواع التنسيق) يضمن رفض المدخلات المشوهة أو الضارة برسائل خطأ واضحة *قبل* الوصول إلى منطقك، وهو أمر ضروري لأنك يجب ألا تثق أبدًا بالمدخلات الخام. يجعل FastAPI هذا إعلانيًا وسهلًا: تتم قيود `Query`/`Path`/`Field` التحقق منها تلقائيًا (إنتاج أخطاء 422 منظمة) وموثقة في نفس الوقت في وثائق API، لذا يتم فرض القواعل التواصل عنها من إعلان واحد. معرفة القيود الشائعة وأنواع التحقق المتخصصة هي معرفة يومية لبناء endpoints آمنة محددة جيدًا — هذه هي طريقة تجاوز فحص النوع الأساسي لفرض قواعد الأعمال الفعلية التي يجب أن تحققها بيانات.