FastAPI CORS Cross-Origin

CORS (Cross-Origin Resource Sharing) — это механизм безопасности, который разрешает или ограничивает веб-страницам запрашивать ресурсы с других доменов. Когда фронтенд и бэкенд разрабатываются отдельно, страница фронтенда обычно работает на другом домене или порту, поэтому необходимо настроить CORS для нормального доступа к API бэкенда.


В чём заключается проблема кросс-доменности

Политика одного источника в браузере запрещает веб-страницам отправлять запросы на другие домены. Например:

Адрес фронтендаАдрес API бэкендаКросс-доменный или нет
http://localhost:3000http://localhost:8000Кросс-доменный (другой порт)
http://example.comhttp://api.example.comКросс-доменный (другой домен)
https://example.comhttp://example.comКросс-доменный (другой протокол)
http://example.comhttp://example.com/apiОдин источник (тот же домен, порт, протокол)

Три элемента одного источника:протокол、доменное имя、порт, если хотя бы один отличается, это кросс-доменный.


Настройка CORS

FastAPI использует StarletteCORSMiddlewareДля обработки кросс-доменных запросов:

Пример

from fastapi import FastAPI
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_originslist[str]Список разрешённых источников cross-originИспользуйте конкретные домены в производственной среде
allow_methodslist[str]Разрешённые методы HTTP["GET", "POST", "PUT", "DELETE"]
allow_headerslist[str]Разрешённые заголовки запросаКонфигурация по требованию
allow_credentialsboolРазрешать ли передачу cookies и аутентификационных данныхУстанавливается, когда требуется аутентификацияTrue
expose_headerslist[str]Заголовки ответа, к которым может получить доступ фронтендКонфигурация по требованию
max_ageintДлительность кэширования preflight-запросов (секунды)600

allow_originsИспользование["*"]Указывает на разрешение всех источников, но этоallow_credentials=TrueНесовместимо. Если нужно передавать куки, необходимо указать конкретный источник.


Среда разработки против продакшен-среды

Среда разработки

Для удобства во время разработки можно разрешить все источники:

Пример

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Среда разработки: разрешить все источники (только для разработки!)
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],         # Разрешить все источники
    allow_credentials=True,
    allow_methods=["*"],         # Разрешить все методы
    allow_headers=["*"],         # Разрешить все заголовки запросов
)

Производственная среда

В продакшен-среде необходимо указать конкретные источники:

Пример

from fastapi import FastAPI
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

setmax_ageПосле этого браузер кэширует результат preflight-проверки и не будет повторно отправлять preflight-запрос в течение указанного времени, что снижает сетевые накладные расходы.


Итог

  • CORS — это механизм безопасности браузера, который необходимо настроить при раздельной разработке фронтенда и бэкенда.
  • ИспользованиеCORSMiddlewareОбработка кросс-доменных запросов
  • В производственной среде обязательно указывайте конкретныйallow_origins, не используйте["*"]
  • allow_credentials=Trueиallow_origins=["*"]несовместимо
  • Промежуточное ПО CORS автоматически обрабатывает preflight-запросы OPTIONS браузера.
Другие расширения