كيف تقوم بتكوين CORS في FastAPI؟

Question

Accepted Answer

**CORS** (Cross-Origin Resource Sharing) هي آلية أمان في المتصفح تتحكم في ما إذا كانت صفحة ويب من **أصل** واحد يمكنها استدعاء API الخاص بك على أصل مختلف. يقوم FastAPI بتكوينها باستخدام **`CORSMiddleware`** المدمج. ستواجه CORS كلما استدعت واجهة أمامية على نطاق/منفذ مختلف API الخاص بك.

## المشكلة التي يعالجها CORS

```text
A React app at http://localhost:3000 calling an API at http://localhost:8000 is
CROSS-ORIGIN (different port). The BROWSER blocks the response unless the API
sends CORS headers permitting that origin.
(origin = scheme + host + port)
```

## تكوين CORSMiddleware

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

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "http://localhost:3000"],  # ALLOWLIST of origins
    allow_credentials=True,         # allow cookies/auth (requires specific origins, not "*")
    allow_methods=["*"],             # or ["GET", "POST", ...]
    allow_headers=["*"],
)
```

يضيف الوسيط رؤوس استجابة CORS الضرورية، مما يخبر المتصفح بالأصول والطرق والرؤوس المسموحة. يفرض المتصفح هذه القواعد.

## الأمان: تقييد الأصول (لا تستخدم "*")

```python
# ❌ allowing all origins — convenient but insecure for credentialed/private APIs
allow_origins=["*"]
# ✅ restrict to your known frontend origins (an allowlist)
allow_origins=["https://app.example.com"]
# NOTE: allow_credentials=True is INCOMPATIBLE with allow_origins=["*"]
```

للإنتاج، **قيّد `allow_origins` بقائمة بيضاء** بدلاً من `*`. بالإضافة إلى ذلك، السماح بالبيانات الاعتماديّة (ملفات تعريف الارتباط/المصادقة) يتطلب أصول محددة — لا يُسمح بالبدل الجامع مع البيانات الاعتماديّة.

## مفهوم خاطئ رئيسي

```text
CORS is enforced by the BROWSER, not the server. It does NOT protect your API from
non-browser clients (curl, Postman, other servers) — those ignore CORS entirely.
CORS only governs what browser JavaScript from other origins may do.
```

## لماذا يهمك ذلك

CORS واحدة من أكثر العقبات شيوعاً في تطوير الويب — تقريباً كل إعداد واجهة أمامية إلى API يواجهها (خاصة في التطوير المحلي مع منافذ مختلفة، وفي الإنتاج مع نطاق واجهة أمامية منفصل)، لذا معرفة كيفية تكوينها مع `CORSMiddleware` الخاص بـ FastAPI معرفة عملية وضرورية متكررة.

فهم *السبب* وراء وجودها (أمان نفس الأصل في المتصفح)، وكيف يختار الخادم الموافقة عبر رؤوس الاستجابة، وكيفية تكوينها (الأصول المسموحة، الطرق، الرؤوس، البيانات الاعتماديّة) ضروري لربط الواجهات الأمامية بـ FastAPI APIs دون حجب الطلبات.

من المهم بنفس القدر تكوينها **بأمان** — تقييد `allow_origins` بقائمة بيضاء محددة بدلاً من البدل الجامع المتساهل `*` (وفهم أن البيانات الاعتماديّة غير متوافقة مع البدل الجامع) — والإمساك بالمفهوم الخاطئ الحاسم وهو أن **CORS آلية في المتصفح وليست تفويضاً للـ API** (لا تحمي من عملاء غير المتصفح).

معرفة كيفية إعداد CORS بشكل صحيح وآمن معرفة مهمة يومية لأي FastAPI API يستهلكها واجهة ويب أمامية.