كيف يعمل middleware في FastAPI؟

Question

Accepted Answer

**Middleware** في FastAPI هو كود يعمل لـ **كل request و response** — يلتف حول endpoints الخاصة بك للتعامل مع المخاوف الشاملة مثل التسجيل والتوقيت و CORS وإضافة headers. يستخدم FastAPI نظام middleware من Starlette (يعتمد على ASGI).

## كتابة middleware مخصص

```python
import time

@app.middleware("http")
async def add_timing(request: Request, call_next):
    start = time.time()
    response = await call_next(request)        # call the endpoint (and any inner middleware)
    response.headers["X-Process-Time"] = str(time.time() - start)   # modify the response
    return response
```

النمط: الكود قبل `await call_next(request)` يعمل في الطريق **للداخل** (قبل endpoint)، و`call_next` يستدعي endpoint، والكود بعده يعمل في الطريق **للخارج** (تعديل response). هذا يلتف حول كل request — هنا، إضافة timing header لجميع responses.

## تدفق request/response

```text
Request  → MW1 → MW2 → endpoint
Response ← MW1 ← MW2 ← endpoint
Middleware wraps the endpoint; runs in order on the way in, reverse on the way out.
```

## Middleware المدمج / الشائع

```python
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)  # CORS
app.add_middleware(GZipMiddleware, minimum_size=1000)                               # compression
```

عادة ما يتم إضافة middleware عبر `add_middleware` — CORS (السماح بالطلبات عبر الأصول)، GZip (ضغط responses)، وفحوصات trusted-host هي built-ins نموذجية.

## استخدامات middleware الشائعة

```text
✓ Logging / request timing / metrics
✓ CORS (cross-origin request handling)
✓ Adding security or custom headers
✓ Response compression (GZip)
✓ Request ID / correlation ID injection
```

## Middleware مقابل dependencies

```text
Middleware   → runs for ALL requests; works at the raw request/response level (headers,
               timing, the whole response). Best for truly global concerns.
Dependencies → per-endpoint (or grouped) logic with access to parsed params, DI, and
               typed values. Best for auth, validation, shared parameters.
→ Use middleware for global cross-cutting concerns; dependencies for endpoint logic.
```

## لماذا يهم

Middleware هو الآلية الصحيحة للمخاوف الشاملة والعالمية في FastAPI — الكود الذي يجب أن ينطبق على كل request و response، مثل التسجيل والتوقيت والـ CORS والضغط والـ custom headers.

فهمه مهم لهيكلة التطبيقات بشكل صحيح: middleware يلتف حول جميع endpoints (يعمل قبل وبعد، مع القدرة على تعديل كل من request و response)، مما يجعله مثاليًا للسلوك الذي يشمل التطبيق بالكامل والذي قد يكون مملًا وعرضة للخطأ إذا كرره في كل endpoint.

معرفة التمييز بين **middleware** (عام، على مستوى request/response الخام) و **dependencies** (لكل endpoint، مع الوصول إلى القيم المحللة/المكتوبة و DI — أفضل للمصادقة والتحقق) هو مفتاح اختيار الأداة الصحيحة.

الاحتياجات الشائعة مثل CORS والضغط يتم التعامل معها بواسطة middleware المدمج، بينما custom middleware يغطي التسجيل والأداة — مما يجعل هذه معرفة عملية ومستخدمة بشكل متكرر لبناء APIs منظمة وقابلة للملاحظة.