ما هو الغرض من `response_model`؟

Question

Accepted Answer

معامل **`response_model`** يعلّن عن شكل استجابة نقطة نهاية معينة. يستخدمه FastAPI **للتحقق والتصفية والتسلسل** للبيانات المرجعة — وللتوثيق في مستندات API. وظيفته الأكثر أهمية: التأكد من أنك تعرّض فقط الحقول المقصودة (مثلاً عدم تسرب كلمة المرور).

## المشكلة: تسرب الحقول الحساسة

```python
class User(BaseModel):
    name: str
    email: str
    password: str        # ⚠️ should NEVER be in the response!

@app.get("/users/{id}")
def get_user(id: int) -> User:
    return db.get_user(id)   # returning the full object would expose the password
```

## الحل: نموذج استجابة منفصل

```python
class UserOut(BaseModel):    # the SAFE public shape — no password
    name: str
    email: str

@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int):
    return db.get_user(id)   # returns a full user, but FastAPI FILTERS it to UserOut
# response → { "name": "...", "email": "..." }  — password stripped automatically
```

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

## ما يفعله response_model

```text
✓ FILTERS the output to only the declared fields (key for hiding sensitive data)
✓ VALIDATES that your response matches the declared schema (catches mistakes)
✓ SERIALIZES the data to JSON correctly
✓ DOCUMENTS the response shape in the OpenAPI/Swagger docs
```

## البديل الحديث: تعليق نوع الإرجاع

```python
@app.get("/users/{id}")
def get_user(id: int) -> UserOut:    # the -> return type works like response_model
    return db.get_user(id)
# response_model_exclude_unset=True → omit fields not explicitly set
```

## لماذا يهم

`response_model` مهم لكل من **الأمان** وتصميم API نظيف.

doره الأكثر أهمية هو منع تسرب البيانات العرضي — بإعلانك بالضبط أي حقول يجب أن تحتويها الاستجابة، يقوم FastAPI بتصفية كل شيء آخر (مثل hash كلمات المرور أو الأعلام الداخلية أو الرموز) حتى لو أرجع الكود كائن قاعدة بيانات كاملة، مما يزيل ثغرة شائعة وخطيرة.

بعيداً عن ذلك، يتحقق من استجاباتك مقابل schema معلنة (اكتشاف الأخطاء حيث تعيد الشكل الخاطئ)، يضمن التسلسل الصحيح، ويوثق الاستجابة في مستندات API التي تم إنشاؤها تلقائياً.

نمط استخدام نماذج input و output منفصلة (مع `response_model` يتحكم في ما يتم تعريضه) هو أفضل ممارسة لـ APIs آمنة وموثقة بشكل جيد، مما يجعل هذه المعرفة مهمة لأي نقطة نهاية تعيد بيانات.