كيف تكتب تحقق مخصص في Pydantic؟

Question

Accepted Answer

بعد القيود المدمجة، يتيح لك Pydantic كتابة **منطق التحقق المخصص** مع محققات الحقول (التحقق من حقل واحد) ومحققات النموذج (التحقق عبر حقول متعددة) — للقواعد التي لا يمكن للقيود البسيطة التعبير عنها. (الصيغة المعروضة هي Pydantic v2.)

## محققات الحقول — التحقق/تحويل حقل واحد

```python
from pydantic import BaseModel, field_validator

class User(BaseModel):
    username: str
    password: str

@field_validator("username")
    @classmethod
    def username_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("username must be alphanumeric")   # → a 422 error
        return v.lower()                                         # can also TRANSFORM the value
```

يشغل `@field_validator` منطق مخصص على حقل: ارفع `ValueError` لرفض المدخلات غير الصحيحة (يحولها FastAPI إلى استجابة واضحة 422)، أو أرجع قيمة محولة (مثل تطبيع الأحرف الصغيرة).

## محققات النموذج — التحقق عبر الحقول

```python
from pydantic import model_validator

class SignupForm(BaseModel):
    password: str
    confirm_password: str

@model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.confirm_password:    # compare MULTIPLE fields
            raise ValueError("passwords do not match")
        return self
```

يشغل `@model_validator(mode="after")` بعد التحقق من جميع الحقول، مع الوصول إلى النموذج بأكمله — يُستخدم للقواعد التي تتضمن **حقول متعددة** (مثل تأكيد تطابق كلمات المرور، أو أن تاريخ البداية يسبق تاريخ النهاية).

## غالباً ما يكون التحقق المدمج كافياً في البداية

```python
class Product(BaseModel):
    price: float = Field(gt=0)          # use Field constraints for simple rules
    sku: str = Field(pattern=r"^[A-Z]{3}-\d+$")
    email: EmailStr                      # specialized types for formats
# reach for custom validators only when constraints/types can't express the rule
```

فضّل قيود `Field` والأنواع المتخصصة للقواعد البسيطة؛ استخدم محققات مخصصة للمنطق التجاري الفعلي.

## لماذا يهم

التحقق المخصص في Pydantic مهم لفرض القواعد التجارية التي تتجاوز فحوصات النوع والقيود البسيطة — وبما أن التحقق حرج للغاية بالنسبة للأمان وسلامة البيانات، فإن القدرة على التعبير عن أي قاعدة ذات قيمة. **محققات الحقول** تتعامل مع منطق الحقل الواحد (فحوصات التنسيق المخصصة، التطبيع/التحويل)، بينما **محققات النموذج** تتعامل مع الحاجة الشائعة للـ **التحقق عبر الحقول** (تطابق كلمات المرور، نطاقات التاريخ، المتطلبات الشرطية) التي لا يمكن للقواعس على مستوى الحقل التعبير عنها.

تندمج المحققات بسلاسة مع FastAPI — يصبح `ValueError` المرفوع استجابة واضحة 422 تلقائياً.

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