FastAPI CORS Cross-Origin
CORS (Cross-Origin Resource Sharing) — это механизм безопасности, который разрешает или ограничивает веб-страницам запрашивать ресурсы с других доменов. Когда фронтенд и бэкенд разрабатываются отдельно, страница фронтенда обычно работает на другом домене или порту, поэтому необходимо настроить CORS для нормального доступа к API бэкенда.
В чём заключается проблема кросс-доменности
Политика одного источника в браузере запрещает веб-страницам отправлять запросы на другие домены. Например:
| Адрес фронтенда | Адрес API бэкенда | Кросс-доменный или нет |
|---|---|---|
http://localhost:3000 | http://localhost:8000 | Кросс-доменный (другой порт) |
http://example.com | http://api.example.com | Кросс-доменный (другой домен) |
https://example.com | http://example.com | Кросс-доменный (другой протокол) |
http://example.com | http://example.com/api | Один источник (тот же домен, порт, протокол) |
Три элемента одного источника:протокол、доменное имя、порт, если хотя бы один отличается, это кросс-доменный.
Настройка CORS
FastAPI использует StarletteCORSMiddlewareДля обработки кросс-доменных запросов:
Пример
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Промежуточное ПО CORS
app.add_middleware(
CORSMiddleware,
allow_origins=[ # Разрешённые источники (список доменов)
"http://localhost:3000", # Сервер разработки фронтенда
"http://localhost:8080",
],
allow_credentials=True, # Разрешить куки
allow_methods=["*"], # Разрешённые HTTP-методы
allow_headers=["*"], # Разрешённые заголовки запроса
)
@app.get("/")
async def root():
return {"message": "Hello World"}
Параметры конфигурации CORS с пояснениями
| Параметр | Type | Описание | рекомендуемое значение |
|---|---|---|---|
allow_origins | list[str] | Список разрешённых источников cross-origin | Используйте конкретные домены в производственной среде |
allow_methods | list[str] | Разрешённые методы HTTP | ["GET", "POST", "PUT", "DELETE"] |
allow_headers | list[str] | Разрешённые заголовки запроса | Конфигурация по требованию |
allow_credentials | bool | Разрешать ли передачу cookies и аутентификационных данных | Устанавливается, когда требуется аутентификацияTrue |
expose_headers | list[str] | Заголовки ответа, к которым может получить доступ фронтенд | Конфигурация по требованию |
max_age | int | Длительность кэширования preflight-запросов (секунды) | 600 |
allow_originsИспользование["*"]Указывает на разрешение всех источников, но этоallow_credentials=TrueНесовместимо. Если нужно передавать куки, необходимо указать конкретный источник.
Среда разработки против продакшен-среды
Среда разработки
Для удобства во время разработки можно разрешить все источники:
Пример
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Среда разработки: разрешить все источники (только для разработки!)
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # Разрешить все источники
allow_credentials=True,
allow_methods=["*"], # Разрешить все методы
allow_headers=["*"], # Разрешить все заголовки запросов
)
Производственная среда
В продакшен-среде необходимо указать конкретные источники:
Пример
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Продакшен-среда: разрешить только определённые домены
app.add_middleware(
CORSMiddleware,
allow_origins=[
"https://example.com", # Домен фронтенда в продакшене
"https://www.example.com", # Домен с www
],
allow_credentials=True,
allow_methods=["GET", "POST", "PUT", "DELETE"],
allow_headers=["Authorization", "Content-Type"],
max_age=600, # Кэш предварительного запроса на 10 минут
)
Используйте в производственной среде
allow_origins=["*"]Это угроза безопасности и может привести к атакам с подделкой межсайтовых запросов (CSRF). Обязательно укажите конкретный домен фронтенда.
Предварительный запрос CORS
Перед отправкой некоторых кросс-доменных запросов браузер сначала отправляетOPTIONSпредварительный запрос, спрашивая у сервера, разрешён ли фактический запрос. Промежуточное ПО CORS автоматически обрабатывает предварительные запросы.
Условия для запросов, требующих предварительного запроса:
- использует
PUT、DELETEНе простые методы, такие как - Заголовок запроса содержит пользовательские поля (например,
Authorization) Content-Typeнеapplication/x-www-form-urlencoded、multipart/form-dataилиtext/plain
set
max_ageПосле этого браузер кэширует результат preflight-проверки и не будет повторно отправлять preflight-запрос в течение указанного времени, что снижает сетевые накладные расходы.
Итог
- CORS — это механизм безопасности браузера, который необходимо настроить при раздельной разработке фронтенда и бэкенда.
- Использование
CORSMiddlewareОбработка кросс-доменных запросов - В производственной среде обязательно указывайте конкретный
allow_origins, не используйте["*"] allow_credentials=Trueиallow_origins=["*"]несовместимо- Промежуточное ПО CORS автоматически обрабатывает preflight-запросы OPTIONS браузера.