يتعامل FastAPI مع الأخطاء من خلال طرح استثناءات يحولها إلى استجابات HTTP مناسبة. HTTPException يغطي معظم الحالات؛ معالجات الاستثناءات المخصصة تتيح لك التحكم في تنسيق الأخطاء عالمياً.
طرح HTTPException
from fastapi import HTTPException
@app.get("/items/{id}")
def get_item(id: int):
item = db.get(id)
if not item:
raise HTTPException(status_code=404, detail="Item not found") # → 404 JSON response
if not item.is_public:
raise HTTPException(status_code=403, detail="Forbidden")
return item
raise HTTPException(status_code=..., detail=...) هي الطريقة الاصطلاحية للعودة برسالة خطأ — FastAPI ينتج استجابة JSON {"detail": "..."} بالحالة المعطاة. يمكن لـ detail أن تكون أي قيمة قابلة للتسلسل JSON (نص، قاموس، قائمة).
أخطاء التحقق تكون تلقائية (422)
When request data fails Pydantic validation, FastAPI AUTOMATICALLY returns a 422
with a structured list of exactly which fields are wrong — you write nothing.
معالجات الاستثناءات المخصصة (التنسيق العام)
from fastapi import Request
from fastapi.responses import JSONResponse
class ItemNotFound(Exception):
def __init__(self, item_id: int): self.item_id = item_id
@app.exception_handler(ItemNotFound) # handle a custom exception type globally
def handle_not_found(request: Request, exc: ItemNotFound):
return JSONResponse(status_code=404, content={"error": f"Item {exc.item_id} not found"})
@app.get("/items/{id}")
def get(id: int):
raise ItemNotFound(id) # raise your domain exception; the handler formats it
معالجات الاستثناءات المخصصة تتيح لك ربط استثناءاتك الخاصة (المجال) بالاستجابات، مما يركز صيغة الأخطاء ويحافظ على نظافة كود المعالج.
تجاوز المعالجات الافتراضية
from fastapi.exceptions import RequestValidationError
@app.exception_handler(RequestValidationError) # customize the 422 validation-error format
def validation_handler(request, exc):
return JSONResponse(status_code=422, content={"errors": exc.errors()})
لماذا يهم
معالجة الأخطاء الصحيحة ضرورية لبناء واجهات برمجة تطبيقات موثوقة واحترافية، وطريقة FastAPI نظيفة ومتسقة.
HTTPException الاصطلاحية تجعل من السهل العودة باستجابات خطأ صحيحة مع رموز الحالة والرسائل المناسبة — أساسية لأي نقطة نهاية قد تفشل (غير موجودة، ممنوعة، حالة سيئة).
بنفس الأهمية أن أخطاء التحقق تُعالج تلقائياً (فشل Pydantic ينتج استجابات 422 منظمة بدون أي كود من جانبك)، وأن معالجات الاستثناءات المخصصة تتيح لك ربط استثناءاتك الخاصة بالاستجابات وفرض تنسيق خطأ متسق عبر كل واجهة برمجة التطبيقات — تحسين الصيانة (منطق الخطأ المركزي) وتجربة العميل (أشكال خطأ متنبأ بها).
فهم HTTPException وأخطاء التحقق التلقائية ومعالجات الاستثناءات المخصصة يغطي الطيف العملي لمعالجة الأخطاء، مما يجعله معرفة مهمة لبناء واجهات برمجة تطبيقات قوية.