كيف يعمل حقن الاعتماديات (Depends)؟

Question

Accepted Answer

نظام **حقن الاعتماديات** في FastAPI يسمح لك بإعلان اعتماديات قابلة لإعادة الاستخدام (دوال/فئات) التي يستدعيها FastAPI و**يحقنها** في عمليات المسار الخاصة بك عبر `Depends()`. يُستخدم للمنطق المشترك مثل جلسات قاعدة البيانات والمصادقة والمعاملات الشائعة — مما يحافظ على الكود جاف وقابل للاختبار.

## اعتمادية أساسية

```python
from fastapi import Depends

# a dependency is just a callable that returns something
def pagination(skip: int = 0, limit: int = 10):
    return {"skip": skip, "limit": limit}

@app.get("/items")
def list_items(params: dict = Depends(pagination)):   # FastAPI calls pagination() and injects the result
    return params
# the skip/limit query params are now handled by the reusable dependency
```

إعلان `params = Depends(pagination)` يخبر FastAPI باستدعاء `pagination` (حل *معاملات* من الطلب أيضًا) ونقل النتيجة إلى دالتك. الاعتمادية قابلة لإعادة الاستخدام عبر العديد من نقاط النهاية.

## الاعتماديات مع التنظيف (yield) — على سبيل المثال جلسات قاعدة البيانات

```python
def get_db():
    db = SessionLocal()
    try:
        yield db                  # provide the session to the endpoint
    finally:
        db.close()                # cleanup runs AFTER the response — guaranteed

@app.get("/users")
def list_users(db = Depends(get_db)):
    return db.query(User).all()    # uses the injected, auto-closed session
```

اعتمادية `yield` توفر مورد وتشغل التنظيف بعد الطلب — النمط القياسي لجلسات قاعدة البيانات (الفتح قبل الإغلاق بعد، تلقائيًا).

## الاعتماديات يمكنها الاعتماد على اعتماديات

```python
def get_current_user(token: str = Depends(get_token)):   # depends on another dependency
    return decode(token)

@app.get("/me")
def me(user: User = Depends(get_current_user)):           # auth via injection
    return user
```

الاعتماديات تشكل شجرة — يحل FastAPI السلسلة كاملة. هذا هو كيفية تنفيذ المصادقة عادة (اعتمادية `get_current_user`).

## اعتماديات الفئة وإعادة الاستخدام

```python
@app.get("/items", dependencies=[Depends(verify_api_key)])   # run a dependency without using its return
def items(): ...                                              # e.g. enforce auth as a side effect
```

## لماذا يهم

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

فهمه ضروري لأنه يدعم الأنماط الأساسية: **اعتمادية `yield`** هي الطريقة القياسية لإدارة جلسات قاعدة البيانات (مع ضمان التنظيف بعد كل طلب)، و**اعتمادية `get_current_user`** هي الطريقة الاصطلاحية لتنفيذ المصادقة.

حقن الاعتماديات يجعل الكود **قابل للاختبار** للغاية — يمكنك تجاوز الاعتماديات بمحاكيات في الاختبارات.

أناقة النظام (الاعتماديات تحل معاملاتها الخاصة من الطلب وتستطيع الاعتماد على اعتماديات أخرى تشكل شجرة والتكامل مع المستندات) تجعله أداة متعددة الاستخدامات لهيكلة التطبيقات الحقيقية، لذا فإن إتقان `Depends` هو مفتاح بناء تطبيقات FastAPI منظمة وسهلة الصيانة وقابلة للاختبار.