Начало работы
Первое API
FastAPI построен на Starlette и Pydantic. uvicorn — ASGI-сервер. --reload включает автоперезагрузку при разработке.
# install FastAPI and uvicorn
pip install fastapi uvicorn
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def read_root():
return {"Hello": "World"}
# run: uvicorn main:app --reloadЗапуск через Uvicorn
Запись 'main:app' означает модуль 'main' и переменную 'app'. Используйте --reload только при разработке; в production запускайте без него и п од менеджером процессов.
# development with auto-reload
uvicorn main:app --reload
# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000
# run programmatically
import uvicorn
if __name__ == "__main__":
uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)Асинхронные обработчики путей
Обработчики путей можно объявлять через 'def' (выполняется в пуле потоков) или 'async def'. Используйте async def, когда функция работает с вводом-выводом через асинхронные библиотеки; блокирующие вызовы внутри async def останавливают цикл событий.
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
async def read_root():
return {"message": "hello"}
@app.get("/sync")
def read_sync():
return {"message": "sync also works"}
# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
import httpx
async with httpx.AsyncClient() as client:
r = await client.get("https://api.example.com")
return r.json()Декораторы обработчиков путей
FastAPI поддерживает все HTTP-методы: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Каждому соответствует декоратор. status_code= в декораторе переопределяет стандартный код успеха.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items")
def list_items(): ...
@app.post("/items")
def create_item(): ...
@app.put("/items/{item_id}")
def replace_item(item_id: int): ...
@app.patch("/items/{item_id}")
def update_item(item_id: int): ...
@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...
@app.options("/items")
def options_items(): ...
@app.head("/items")
def head_items(): ...JSON-ответ и статус
Возврат dict или list автоматически преобразуется в JSON с кодом 200 (или вашим status_code). Для полного контроля над статусом, заголовками и содержимым возвращайте JSONResponse или Response напрямую.
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse
app = FastAPI()
@app.get("/plain")
def plain():
return {"key": "value"} # auto JSON, 200 OK
@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
return {"id": 1}
@app.get("/custom")
def custom():
return JSONResponse(
status_code=418,
content={"error": "I'm a teapot"},
headers={"X-Custom": "yes"},
)Структура проекта
Растущее приложение разбивайте на модули с APIRouter и регистрируйте через app.include_router(). Схемы Pydantic, настройку БД и зависимости держите в отдельных файлах для удобства поддержки.
myapp/
main.py # creates the FastAPI app
routers/
users.py # APIRouter for /users
items.py # APIRouter for /items
models/
schemas.py # Pydantic models
database.py # DB engine & session
dependencies.py # shared Depends functions
tests/
test_main.py
# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")Параметры пути
Базовые параметры пути
Значения из пути приходят строками, если не добавить аннотацию типа. Имя параметра в пути должно точно совпадать с именем аргумента функции.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id):
return {"item_id": item_id}
# GET /items/42 -> {"item_id": "42"} (string by default)Преобразование типов
Аннотация типа (int, float, bool, str, Enum) заставляет FastAPI проверить и преобразовать значение пути. Некорректные значения дают ответ 422 с понятным сообщением об ошибке.
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: int):
return {"item_id": item_id}
# GET /items/3 -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)Валидация пути
Path() добавляет метаданные и ограничения к параметру пути. Числовые ограничения: ge (>=), gt (>), le (<=), lt (<). Параметры пути всегда обязательны, поэтому Path() не может задать значение по умолчанию.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(
item_id: int = Path(
title="The ID of the item",
description="Must be a positive integer",
ge=1,
le=1000,
),
):
return {"item_id": item_id}Числовые ограничения
Используйте ge/gt/le/lt для параметров пути int или float, чтобы задать числовые диапазоны. Вместе они дают точную проверку границ с автоматическими ошибками 422.
from fastapi import FastAPI, Path
app = FastAPI()
@app.get("/ratio/{value}")
def ratio(
value: float = Path(gt=0, lt=1), # 0 < value < 1
):
return {"value": value}
@app.get("/page/{page}")
def page(
page: int = Path(ge=1), # >= 1
size: int = Path(le=100), # <= 100
):
return {"page": page, "size": size}Порядок маршрутов важен
Маршруты сопоставляются в порядке объявления. Объявляйте конкретные пути вроде /users/me раньше динамических шаблонов вроде /users/{user_id}, иначе динамический маршрут перекроет конкретный.
from fastapi import FastAPI
app = FastAPI()
@app.get("/users/me")
def read_current_user():
return {"user": "me"}
@app.get("/users/{user_id}")
def read_user(user_id: str):
return {"user_id": user_id}
# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} patternEnum в параметрах пути
Тип Enum для параметра пути ограничивает его заданными значениями и создаёт enum-схему в документации OpenAPI. Наследуйтесь от (str, Enum), чтобы значения сериализовались как строки.
from enum import Enum
from fastapi import FastAPI
class ModelName(str, Enum):
alexnet = "alexnet"
resnet = "resnet"
lenet = "lenet"
app = FastAPI()
@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
if model_name is ModelName.alexnet:
return {"model": model_name, "layers": 5}
return {"model": model_name}
# GET /models/resnet -> {"model": "resnet"}Query-параметры
Базовые query-параметры
Параметры функции, которых нет в пути, становятся query-параметрами. Значение по умолчанию делает их необязательными; оно используется, когда ключа в запросе нет.
from fastapi import FastAPI
app = FastAPI()
fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
return fake_items[skip : skip + limit]
# GET /items?skip=0&limit=2
# GET /items -> skip=0, limit=10Необязательные query-параметры
Используйте Optional[str] = None (или str | None = None в Python 3.10+) для query-параметра, который можно не передавать. Обязательные параметры просто не имеют значения по умолчанию.
from typing import Optional
from fastapi import FastAPI
app = FastAPI()
@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
if q:
return {"item_id": item_id, "q": q}
return {"item_id": item_id}
# GET /items/1?q=hello
# GET /items/1 (q is None)Валидация query-параметров
Query() добавляет проверки: min_length/max_length для строк, ge/gt/le/lt для чисел, pattern (regex) для формата строки. Используйте default=, чтобы задать значение и при этом применить ограничения.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
return {"q": q}
@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
return {"limit": limit}Преобразование в bool
Bool-параметры принимают много истинных значений: true, 1, yes, on (без учёта регистра). Всё остальное трактуется как false. Некорректные значения вроде ?active=maybe дают 422.
from fastapi import FastAPI
app = FastAPI()
@app.get("/flags")
def flags(active: bool = False):
return {"active": active}
# GET /flags?active=true -> {"active": true}
# GET /flags?active=1 -> {"active": true}
# GET /flags?active=yes -> {"active": true}
# GET /flags?active=off -> {"active": false}Списки в query-параметрах
Параметр List[str] принимает один и тот же ключ, повторённый в строке запроса. Используйте Query(default=[]) для пустого списка по умолчанию или Query(default=None), чтобы разрешить отсутствие значения.
from typing import List
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
return {"q": q}
# GET /items?q=a&q=b&q=c -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or nullОбязательные query-параметры
Query(...) (многоточие) объявляет обязательный query-параметр, сохраняя метаданные валидации. Параметр с аннотацией без значения по умолчанию и без Query(...) тоже обязателен.
from fastapi import FastAPI, Query
app = FastAPI()
@app.get("/items")
def read_item(q: str = Query(...)):
return {"q": q}
# GET /items?q=hello -> ok
# GET /items -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as requiredТело запроса (Pydantic)
Основы BaseModel
BaseModel Pydantic, объявленный параметром функции, становится JSON-телом запроса. FastAPI проверяет данные, преобразует типы и возвращает 422 при ошибке. Поля со значениями по умолчанию необязательны.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
in_stock: bool = True
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
# POST /items body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}Типы полей и ограничения
Field() добавляет ограничения и метаданные атрибутам модели: min_length/max_length для строк, gt/ge/lt/le для чисел, default_factory для изменяемых значений по умолчанию. model_config с json_schema_extra добавляет примеры в документацию.
from pydantic import BaseModel, Field
from typing import Optional
class Item(BaseModel):
name: str = Field(min_length=1, max_length=100)
price: float = Field(gt=0, description="must be positive")
tax: Optional[float] = None
tags: list[str] = Field(default_factory=list)
model_config = {
"json_schema_extra": {
"examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
}
}Вложенные модели
Модели можно вкладывать: объявите другую BaseModel как тип поля. FastAPI рекурсивно проверяет всю вложенную структуру, а сгенерированная схема OpenAPI отражает вложенные объекты.
from pydantic import BaseModel
from typing import Optional
class Image(BaseModel):
url: str
name: str
class Item(BaseModel):
name: str
description: Optional[str] = None
image: Optional[Image] = None
images: list[Image] = []
# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}Валидация полей
Используйте @field_validator (Pydantic v2), чтобы добавить свою логику проверки поля. Бросьте ValueError, чтобы отклонить ввод (FastAPI вернёт 422). Верните (возможно, преобразованное) значение, чтобы сохранить его.
from pydantic import BaseModel, field_validator
class User(BaseModel):
name: str
email: str
@field_validator("email")
@classmethod
def email_must_contain_at(cls, v: str) -> str:
if "@" not in v:
raise ValueError("must contain @")
return v.lower()
@field_validator("name")
@classmethod
def name_stripped(cls, v: str) -> str:
return v.strip()Необязательные поля и значения по умолчанию
Поле обязательно только если у него нет значения по умолчанию и оно не Optional. Optional[str] = None — стандартный шаблон необязательного nullable-поля; обычное значение вроде 0.0 делает поле необязательным с этим значением.
from pydantic import BaseModel
from typing import Optional
class Item(BaseModel):
name: str # required
description: Optional[str] = None # optional, defaults to None
price: float = 0.0 # optional, defaults to 0.0
tags: list[str] = [] # optional, defaults to empty list
# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}Тело вместе с путём и query
Параметры пути, query и тела могут сосуществовать в одной операции. FastAPI решает так: если параметр есть в пути — это параметр пути; Pydantic-модель (или Body()) — тело; иначе query. Необязательному телу нужно значение по умолчанию None.
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(
item_id: int = Path(ge=1),
q: Optional[str] = Query(default=None),
item: Item = None,
):
result = {"item_id": item_id, **item.model_dump()}
if q:
result["q"] = q
return resultМодель ответа
Основы response_model
response_model фильтрует возвращаемые данны е до полей, описанных в модели, даже если вы вернули объект с лишними полями. Это стандартный способ скрыть чувствительные поля вроде паролей.
from fastapi import FastAPI
from pydantic import BaseModel
class User(BaseModel):
username: str
email: str
hashed_password: str
class UserOut(BaseModel):
username: str
email: str
app = FastAPI()
@app.get("/users/me", response_model=UserOut)
def read_user():
return User(username="bob", email="[email protected]", hashed_password="secret")
# response: {"username": "bob", "email": "[email protected]"} (no password)Исключение полей
response_model_include и response_model_exclude позволяют задать белый или чёрный список полей для маршрута без создания новых моделей. Передавайте множество имён полей. Они применяются дополнительно к response_model.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
secret: str
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
return {"name": "Apple", "price": 0.5, "secret": "hidden"}
@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
return [{"name": "Apple", "price": 0.5, "secret": "x"}]Ответ-список
Используйте response_model=list[Model] (или List[Model]), чтобы объявить, что endpoint возвращает массив объектов. FastAPI проверяет и сериализует каждый элемент списка.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.get("/items", response_model=list[Item])
def list_items():
return [
{"name": "Apple", "price": 0.5},
{"name": "Banana", "price": 0.3},
]
# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]Исключение не заданных и значений по умолчанию
exclude_unset опускает поля, которые клиент не присылал (остаются только явно заданные). exclude_defaults опускает поля, равные значениям по умолчанию; exclude_none опускает поля со значением None. Полезно для разреженных ответов.
from fastapi import FastAPI
from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str | None = None
price: float = 0.0
tax: float = 0.0
app = FastAPI()
@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5} (description, tax omitted)
# also: response_model_exclude_defaults=True
# response_model_exclude_none=TrueОтвет через alias
Field(alias=...) позволяет входному JSON использовать другое имя ключа, чем атрибут Python. response_model_by_alias=True выводит данные тоже по alias. populate_by_name=True дополнительно разрешает исходное имя атрибута на входе.
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field
class Item(BaseModel):
model_config = ConfigDict(populate_by_name=True)
name: str = Field(alias="itemName")
price: float
app = FastAPI()
@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
return item
# input: {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}Ответ в виде словаря
Возврат dict или list автоматически сериализуется в JSON. response_class меняет тип ответа по умолчанию (HTMLResponse, PlainTextResponse), а возврат подкласса Response даёт полный контроль.
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse
app = FastAPI()
@app.get("/dict")
def dict_resp():
return {"a": 1, "b": 2} # auto JSON
@app.get("/text", response_class=PlainTextResponse)
def text_resp():
return "plain text response"
@app.get("/raw")
def raw_resp():
return JSONResponse(content={"a": 1}, status_code=200)Формы и UploadFile
Данные формы
Form() объявляет параметр, разбираемый из application/x-www-form-urlencoded или multipart-формы. В одной операции нельзя смешивать Form() с JSON-телом (BaseModel) — выберите один тип содержимого.
from fastapi import FastAPI, Form
app = FastAPI()
@app.post("/login")
def login(username: str = Form(), password: str = Form()):
return {"username": username}
# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secretОсновы UploadFile
UploadFile — потоковое представление файла с .filename, .content_type, .read(), .write(), .close(). В async def используйте 'await file.read()'. Для больших файлов предпочитайте file.file (SpooledTemporaryFile), чтобы не грузить всё в память.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
contents = await file.read()
return {
"filename": file.filename,
"size": len(contents),
"content_type": file.content_type,
}Несколько файлов
Объявите list[UploadFile], чтобы принять несколько файлов в одном запросе. Каждый файл отправляется с одним и тем же именем поля. Порядок файлов в списке совпадает с порядком отправки.
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
return [
{"filename": f.filename, "size": len(await f.read())}
for f in files
]
# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploadsФайл и форма вместе
Form() и UploadFile (File()) можно сочетать в одном endpoint, так как оба используют multipart/form-data. Но их по-прежнему нельзя сочетать с JSON-телом BaseModel.
from fastapi import FastAPI, UploadFile, File, Form
app = FastAPI()
@app.post("/items")
async def create_item(
name: str = Form(),
description: str = Form(),
file: UploadFile = File(),
):
return {
"name": name,
"description": description,
"file": file.filename,
}Сохранение загруженного файла
Для небольших файлов shutil.copyfileobj эффективно переписывает SpooledTemporaryFile на диск. Для очень больших файлов читайте частями (например, по 1 МБ), чтобы экономить память. Всегда очищайте file.filename, чтобы избежать path traversal.
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile
app = FastAPI()
@app.post("/save")
async def save_file(file: UploadFile):
dest = Path("uploads") / file.filename
dest.parent.mkdir(exist_ok=True)
with dest.open("wb") as buf:
shutil.copyfileobj(file.file, buf)
return {"saved_to": str(dest)}
# async alternative for large files:
# async with dest.open("wb") as buf:
# while chunk := await file.read(1024 * 1024):
# buf.write(chunk)Метаданные и размер файла
Проверяйте file.content_type и размер до обработки. После read() курсор в конце; вызовите 'await file.seek(0)', чтобы вернуться к началу, если нужно читать снова. Настоящая проверка типа должна смотреть на magic bytes, а не только на заголовок.
from fastapi import FastAPI, UploadFile, File
app = FastAPI()
@app.post("/validate")
async def validate(file: UploadFile = File(...)):
# allowed types
allowed = {"image/png", "image/jpeg"}
if file.content_type not in allowed:
return {"error": "unsupported type"}
contents = await file.read()
max_size = 5 * 1024 * 1024 # 5 MB
if len(contents) > max_size:
return {"error": "file too large"}
await file.seek(0) # rewind so later reads work
return {"filename": file.filename, "size": len(contents)}Внедрение зависимостей
Базовый Depends
Depends() внедряет возвращаемое значение функции в обработчик пути. Общая логика (пагинация, разбор, сессии БД) живёт в одном месте и переиспользуется в разных endpoint. Параметры зависимости тоже попадают в документацию OpenAPI.
from fastapi import FastAPI, Depends
app = FastAPI()
def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
return commons
@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
return commonsЗависимости-классы
Класс с __init__ может быть зависимостью: FastAPI вызывает его как функцию. Используйте Depends(CommonQueryParams) или сокращённое Depends(), когда параметр аннотирован классом. Внедряется экземпляр.
from fastapi import FastAPI, Depends
class CommonQueryParams:
def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
self.q = q
self.skip = skip
self.limit = limit
app = FastAPI()
@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}
# shorthand: commons = Depends() infers the typeВложенные зависимости
Зависимости сами могут зависеть от других зависимостей, образуя граф. FastAPI разрешает всё дерево, кеширует результат каждого в рамках запроса и пробрасывает исключения. Идеально для многоуровневой аутентификации (токен -> пользователь -> права).
from fastapi import FastAPI, Depends, Header, HTTPException
def get_token(authorization: str = Header()):
if not authorization.startswith("Bearer "):
raise HTTPException(status_code=401, detail="invalid header")
return authorization.removeprefix("Bearer ")
def get_current_user(token: str = Depends(get_token)):
if token != "admin-token":
raise HTTPException(status_code=403, detail="forbidden")
return {"username": "admin"}
app = FastAPI()
@app.get("/me")
def me(user: dict = Depends(get_current_user)):
return userЗависимости с yield (очистка)
Генератор-зависимость (yield) идеален для ресурсов, требующих очистки: сессии БД, файловые дескрипторы, транзакции. Код после yield выполняется как финализатор, даже если маршрут бросил исключение. В одной зависимости допускается только один yield.
from fastapi import FastAPI, Depends
def get_db():
db = open_db_session() # acquire resource
try:
yield db # injected into the route
finally:
db.close() # always runs after the request
app = FastAPI()
@app.get("/items")
def list_items(db = Depends(get_db)):
return db.query("SELECT * FROM items")Глобальные зависимости
Передайте dependencies=[...] в FastAPI() (или APIRouter), чтобы применять их на всех маршрутах без внедрения результата. Полезно для глобальной аутентификации, rate limiting и логирования запросов.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "supersecret":
raise HTTPException(status_code=400, detail="X-Token missing")
def verify_key(x_key: str = Header()):
if x_key != "realkey":
raise HTTPException(status_code=400, detail="X-Key missing")
# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])
@app.get("/items")
def list_items():
return [{"item": "a"}] # token & key already checkedЗависимости для конкретного маршрута
Используйте dependencies=[Depends(...)] в декораторе (или APIRouter), чтобы пот ребовать зависимость для отдельных маршрутов без использования её результата. Так подписи маршрутов остаются чистыми, а проверки всё равно выполняются.
from fastapi import FastAPI, Depends, Header, HTTPException
def verify_token(x_token: str = Header()):
if x_token != "secret":
raise HTTPException(status_code=401, detail="bad token")
app = FastAPI()
@app.get("/public")
def public():
return {"open": True}
@app.get("/private", dependencies=[Depends(verify_token)])
def private():
return {"secret": "data"}Безопасность (HTTPBasic / OAuth2 / JWT)
HTTP Basic Auth
HTTPBasic разбирает заголовок Authorization: Basic в имя пользователя и пароль. Используйте secrets.compare_digest (а не ==), чтобы предотвратить timing-атаки. Всегда возвращайте 401 с WWW-Authenticate: Basic, чтобы браузер запросил учётные данные.
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
security = HTTPBasic()
app = FastAPI()
def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
correct_user = secrets.compare_digest(credentials.username, "admin")
correct_pass = secrets.compare_digest(credentials.password, "secret")
if not (correct_user and correct_pass):
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Invalid credentials",
headers={"WWW-Authenticate": "Basic"},
)
return credentials.username
@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
return {"user": user}OAuth2 Password Bearer
OAuth2PasswordBearer объявляет, что маршруты ждут Bearer-токен; зависимость извлекает его из заголовка Authorization. tokenUrl говорит интерфейсу документации, куда отправлять учётные данные. Сам токен — просто строка, пока вы его не проверите.
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()
@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
return {"token": token}
# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>Создание JWT-токена
Используйте python-jose (или PyJWT) для подписи токенов. Утверждение 'sub' (subject) обычно хранит имя пользователя или id, а 'exp' задаёт срок действия. SECRET_KEY должен быть длинным, случайным и загружаться из окружения — никогда не коммитьте его.
from datetime import datetime, timedelta, timezone
from jose import jwt
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def create_access_token(data: dict, expires_minutes: int = 30) -> str:
to_encode = data.copy()
expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
to_encode.update({"exp": expire})
return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...Декодирование JWT-токена
jwt.decode проверяет подпись и утверждение 'exp' автоматически, при неудаче бросая JWTError. Сопоставьте зависимос ть с 401 и WWW-Authenticate: Bearer, чтобы клиент знал о необходимости валидного токена.
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"
def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
try:
payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
username: str | None = payload.get("sub")
if username is None:
raise credentials_exception
return username
except JWTError:
raise credentials_exception
credentials_exception = HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Could not validate credentials",
headers={"WWW-Authenticate": "Bearer"},
)Хеширование паролей
Никогда не храните пароли в открытом виде. passlib с bcrypt (или argon2) выполняет соль и хеширование. verify() сравнивает открытый ввод с сохранённым хешем. pip install passlib[bcrypt] установит бэкенд bcrypt.
from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def hash_password(plain: str) -> str:
return pwd_context.hash(plain)
def verify_password(plain: str, hashed: str) -> bool:
return pwd_context.verify(plain, hashed)
# usage when issuing tokens:
def authenticate_user(username: str, password: str):
user = fake_db.get(username)
if not user or not verify_password(password, user.hashed_password):
return False
return userПоток входа OAuth2
OAuth2PasswordRequestForm читает имя пользователя и пароль из POST с form-encoding (стандартный password flow OAuth2). Возвращайте access_token и token_type: 'bearer'. Именно на этот endpoint указывает tokenUrl в OAuth2PasswordBearer.
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
app = FastAPI()
@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
user = authenticate_user(form.username, form.password)
if not user:
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail="Incorrect username or password",
)
token = create_access_token({"sub": user.username})
return {"access_token": token, "token_type": "bearer"}
# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.Middleware
Добавление middleware
@app.middleware('http') регистрирует функцию, оборачивающую каждый запрос. Она должна дождаться call_next(request), получить ответ, а затем может его проверить или изменить перед возвратом. Middleware работает для всех маршрутов.
import time
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_process_time(request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
duration = time.perf_counter() - start
response.headers["X-Process-Time"] = f"{duration:.4f}"
return responseMiddleware для своих заголовков
Middleware — правильное место для заголовков, которые должны быть в каждом ответе (заголовки безопасности, баннер сервера, ID трассировки). Меняйте объект ответа после ожидания call_next.
from fastapi import FastAPI, Request
app = FastAPI()
@app.middleware("http")
async def add_banner(request: Request, call_next):
response = await call_next(request)
response.headers["X-Powered-By"] = "FastAPI"
response.headers["X-Frame-Options"] = "DENY"
return response
# every response now carries these headersBaseHTTPMiddleware
Для переиспользуемого настраиваемого middleware наследуйтесь от BaseHTTPMiddleware и регистрируйте через app.add_middleware(MyMiddleware, **options). Так же добавляются встроенные middleware CORS, GZip и TrustedHost.
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request
class TimingMiddleware(BaseHTTPMiddleware):
async def dispatch(self, request: Request, call_next):
start = time.perf_counter()
response = await call_next(request)
response.headers["X-Duration"] = str(time.perf_counter() - start)
return response
app = FastAPI()
app.add_middleware(TimingMiddleware)
# class-based middleware is reusable and configurableРедирект на HTTPS
HTTPSRedirectMiddleware возвращает редирект 308 на HTTPS-версию любого HTTP-запроса. Используйте его за балансировщиком, который завершает TLS, чтобы гарантировать переход клиентов на защищённое соединение.
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware
app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)
# all HTTP requests are redirected to HTTPS (308)Доверенные хосты
TrustedHostMiddleware отклоняет запросы, чей заголовок Host не входит в белый список, предотвращая атаки через подмену Host. Поддерживаются шаблоны вроде '*.example.com'. Всегда включайте 'localhost' для локальной разработки.
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware
app = FastAPI()
app.add_middleware(
TrustedHostMiddleware,
allowed_hosts=["example.com", "*.example.com", "localhost"],
)
# requests with a disallowed Host header get a 400 responseПорядок middleware
Starlette выполняет middleware в порядке LIFO для входящих запросов: последний добавленный работает первым. Добавляйте CORS рано (чтобы работал preflight), а GZip позже. Помните об этом, когда заголовок одного middleware не виден другому.
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])
# request flow: CORS -> GZip -> route
# response flow: route -> GZip -> CORSCORS
Настройка CORSMiddleware
CORSMiddleware обрабатывает CORS preflight (OPTIONS) и добавляет заголовки Access-Control-*. allow_origins должен перечислять точные разрешённые источники; в production используйте список конкретных URL, а не ['*'].
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"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
@app.get("/api/data")
def data():
return {"data": 1}Разрешить все источники (только для разработки)
allow_origins=['*'] разрешает любой источник, но не сочетается с allow_credentials=True (браузеры это отклоняют). Используйте только для полностью публичных API при разработке; в production перечисляйте реальные источники.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
# allow_credentials=True CANNOT be combined with allow_origins=["*"]
)Разрешить учётные данные
allow_credentials=True позволяет браузеру отправлять cookie и заголовки Authorization между источниками. Это требует конкретных источников (никогда '*'). Браузер ставит в ответах Access-Control-Allow-Credentials: true.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_credentials=True, # send cookies / Authorization
allow_methods=["GET", "POST"],
allow_headers=["Authorization", "Content-Type"],
)
# needed when the frontend sends cookies or credentials with requestsРазрешённые методы и заголовки
allow_methods/allow_headers ограничивают, что браузер может отправить. expose_headers перечисляет заголовки ответа, которые разрешено читать фронтенд-JavaScript (иначе браузеры скрывают свои заголовки). Ответы preflight кешируются браузером.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
expose_headers=["X-Total-Count", "X-Process-Time"],
)
# expose_headers lets the frontend JS read these response headersPreflight-запросы
Для «непростых» запросов (свои заголовки, PUT/DELETE, JSON content type) браузер отправляет preflight OPTIONS. CORSMiddleware перехватывает OPTIONS и отвечает разрешёнными методами и заголовками. max_age задаёт, как долго браузер кеширует этот ответ.
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
app.add_middleware(
CORSMiddleware,
allow_origins=["https://app.example.com"],
allow_methods=["*"],
allow_headers=["*"],
max_age=600, # browser caches preflight result for 600s
)
# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.Динамическая проверка источников
Для динамических белых списков используйте allow_origin_regex (сопоставление с Origin запроса) вместо статического списка. Удобно, когда валидные источники следуют шаблону (например, любой поддомен example.com).
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
app = FastAPI()
VALID_DOMAINS = {"example.com", "staging.example.com"}
def origin_check(origin: str) -> str | None:
if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
return origin
return None
app.add_middleware(
CORSMiddleware,
allow_origin_regex=r"https://.*\.example\.com",
allow_methods=["*"],
allow_headers=["*"],
)Обработка исключений
Выброс HTTPException
raise HTTPException в любом месте маршрута или зависимости прерывает обработку и возвращает ответ с ошибкой. detail может быть строкой, словарём или списком — он становится полем JSON 'detail'. headers добавляет заголовки ответа.
from fastapi import FastAPI, HTTPException, status
app = FastAPI()
items = {1: "Apple", 2: "Banana"}
@app.get("/items/{item_id}")
def read_item(item_id: int):
if item_id not in items:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Item not found",
headers={"X-Error": "missing"},
)
return {"item": items[item_id]}Своё исключение
Зарегистрируйте обработчик через @app.exception_handler(MyException), чтобы превратить своё исключение в HTTP-ответ. Обработчик получает запрос и исключение. Так централизуется формат ошибок предметной области.
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
class UnicornException(Exception):
def __init__(self, name: str):
self.name = name
app = FastAPI()
@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
return JSONResponse(
status_code=418,
content={"message": f"Oops, {exc.name} did it again"},
)
@app.get("/unicorns/{name}")
def read_unicorn(name: str):
if name == "yolo":
raise UnicornException(name=name)
return {"name": name}Переопределение ошибки валидации
RequestValidationError возникает, когда ввод не проходит валидацию Pydantic. Переопределите его обработчик через @app.exception_handler(RequestValidationError), чтобы изменить форму ответа 422, например под общий формат ошибок компании.
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
app = FastAPI()
@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
return JSONResponse(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
content={
"success": False,
"errors": exc.errors(),
"body": exc.body,
},
)Переопределение обработчика HTTPException
Переопределите стандартный обработчик HTTPException, чтобы обеспечить единый JSON-формат ошибок для всех выброшенных HTTPException. При перепривязке обработчика импортируйте класс как fastapi.exceptions.HTTPException (тот же, что используется в raise).
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException
app = FastAPI()
@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
return JSONResponse(
status_code=exc.status_code,
content={
"success": False,
"status": exc.status_code,
"message": exc.detail,
},
headers=exc.headers,
)Частые коды состояния
Модуль status даёт именованные константы для всех HTTP-кодов, избавляя от магических чисел. 200 (по умолчанию для GET), 201 (создано), 204 (нет содержимого), 422 (ошибка валидации) — самые частые в приложениях FastAPI.
from fastapi import FastAPI, status
app = FastAPI()
@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}
@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}
@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None
@app.get("/not-found")
def missing():
# raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
...
# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERRORОбщий обработчик исключений
Обработчик для базового Exception перехватывает всё, что не обработано иначе, не давая трассировкам стека утекать клиентам. Всегда логируйте полную трассировку на сервере, а клиенту возвращайте общий 500.
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
logger = logging.getLogger("uvicorn.error")
app = FastAPI()
@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
logger.exception("Unhandled error on %s", request.url.path)
return JSONResponse(
status_code=500,
content={"detail": "Internal Server Error"},
)
@app.get("/boom")
def boom():
raise RuntimeError("something exploded")Фоновые задачи
Основы BackgroundTasks
BackgroundTasks выполняет функции после отправки ответа — идеально для работы «отправил и забыл»: логирование, письма, инвалидация кеша. add_task планирует функцию (и аргументы), не блокируя ответ.
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def write_log(message: str):
with open("log.txt", "a") as f:
f.write(message + "\n")
@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
background_tasks.add_task(write_log, "notification sent")
return {"message": "notification queued"}Несколько задач
Добавляйте сколько угодно задач: они выполняются последовательно в порядке добавления после возврата ответа. Так как они идут в том же процессе, держите их быстрыми и неблокирующими или переносите в настоящую очередь (Celery, RQ, Dramatiq).
from fastapi import FastAPI, BackgroundTasks
app = FastAPI()
def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...
@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
background_tasks.add_task(send_email, "[email protected]", "Welcome")
background_tasks.add_task(update_cache, "user_count")
background_tasks.add_task(notify_slack, "new signup")
return {"status": "ok"}Задача с зависимостями
BackgroundTasks внедряется как любая зависимость. Функция задачи может получить значения (например, сессию БД), захваченные на момент запроса. Учтите, что ресурсы зависимостей с yield закрываются после завершения задач: задачи выполняются в рамках жизненного цикла запроса.
from fastapi import FastAPI, BackgroundTasks, Depends
app = FastAPI()
def get_db_session():
db = "session"
yield db
def write_log(db, message: str):
print(db, message)
@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
background_tasks.add_task(write_log, db, "list called")
return {"items": []}Асинхронная функция задачи
Фоновые задачи могут быть синхронными (выполняются в пуле потоков) или асинхронными (ожидаются в цикле событий). Асинхронные задачи используйте для ввода-вывода через асинхронные библиотеки, синхронные — для CPU-нагрузки и блокирующей работы.
from fastapi import FastAPI, BackgroundTasks
import httpx
app = FastAPI()
async def fetch_url(url: str):
async with httpx.AsyncClient() as client:
r = await client.get(url)
return r.status_code
@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
background_tasks.add_task(fetch_url, url)
return {"queued": url}Background против Celery
BackgroundTasks используйте для лёгкой некритичной работы, которой можно потерять при перезапуске. Для задач, которые должны переживать падения, повторяться и масштабироваться между машинами, берите настоящую очередь (Celery, RQ, Dramatiq, Arq) с брокером вроде Redis или RabbitMQ.
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
tasks.add_task(small_job)
return {"ok": True}
# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
# big_job.delay(payload)
# return {"queued": True}Пример отправки письма
Отправка письма — классический сценарий BackgroundTasks: это медленно, и пользователь не должен ждать. Ответ возвращается сразу, а письмо уходит после. При большом объёме предпочитайте очередь и SDK почтового сервиса с повторами.
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr
class Message(BaseModel):
to: EmailStr
subject: str
body: str
app = FastAPI()
def send_email(to: str, subject: str, body: str):
# smtplib or your provider's SDK
import smtplib
with smtplib.SMTP("localhost") as s:
s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")
@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
tasks.add_task(send_email, msg.to, msg.subject, msg.body)
return {"status": "queued", "to": msg.to}WebSocket
Основы WebSocket
Используйте @app.websocket() для endpoint WebSocket. Нужно вызвать accept() до отправки и получения. Функция обычно зациклена на чтении сообщений; receive_text/receive_bytes/receive_json ожидают данные от клиента.
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
await ws.accept()
while True:
data = await ws.receive_text()
await ws.send_text(f"echo: {data}")
# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);Отправка JSON
send_json() и receive_json() сами занимаются сериализацией, обмениваясь JSON-объектами через сокет. Для бинарных данных используйте send_bytes/receive_bytes. Каждая отправка и приём — отдельный фрейм WebSocket.
import json
from fastapi import FastAPI, WebSocket
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
while True:
msg = await ws.receive_json()
await ws.send_json({"reply": msg.get("text", "").upper()})
# send_text / send_bytes / send_json helpers are availableЗакрытие WebSocket
WebSocketDisconnect возникает при закрытии соединения клиентом — ловите его для очистки. Для нормального закрытия вызывайте ws.close(code=1000); частые коды: 1000 (нормально), 1008 (нарушение политики), 1011 (ошибка сервера).
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
app = FastAPI()
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
await ws.accept()
try:
while True:
data = await ws.receive_text()
if data == "quit":
await ws.close(code=1000)
break
await ws.send_text(data)
except WebSocketDisconnect:
print("client disconnected")Менеджер соединений
ConnectionManager отслеживает актив ные сокеты, чтобы рассылать сообщения всем подключённым клиентам (например, в чате). Всегда удаляйте сокет при отключении, чтобы не отправлять в закрытые соединения и ограничивать память.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect
class ConnectionManager:
def __init__(self):
self.active: list[WebSocket] = []
async def connect(self, ws: WebSocket):
await ws.accept()
self.active.append(ws)
def disconnect(self, ws: WebSocket):
self.active.remove(ws)
async def broadcast(self, message: str):
for ws in self.active:
await ws.send_text(message)
manager = ConnectionManager()
app = FastAPI()
@app.websocket("/chat")
async def chat(ws: WebSocket):
await manager.connect(ws)
try:
while True:
msg = await ws.receive_text()
await manager.broadcast(msg)
except WebSocketDisconnect:
manager.disconnect(ws)Аутентификация WebSocket через query-параметр
Браузеры не могут задавать свои заголовки для WebSocket, поэтому токены аутентификации часто передают query-параметром (или через cookie). Проверьте данные до accept() и закрывайте с кодом 1008 (нарушение политики), если доступа нет.
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException
app = FastAPI()
async def authenticate(token: str) -> str:
if token != "secret":
raise HTTPException(status_code=401)
return "alice"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
token = ws.query_params.get("token")
if not token:
await ws.close(code=1008)
return
user = await authenticate(token)
await ws.accept()
try:
while True:
data = await ws.receive_text()
await ws.send_text(f"{user}: {data}")
except WebSocketDisconnect:
passWebSocket с зависимостями
Зависимости можно использовать в WebSocket-endpoint так же, как в HTTP-маршрутах, но осмысленны только те, что читают данные начального рукопожатия (заголовки, query-параметры, cookie): тела запроса нет. Внедряйте их через Depends() как обычно.
from fastapi import FastAPI, WebSocket, Depends, Header
app = FastAPI()
def token_validator(token: str = Header(default="")):
# for WS, headers come from the initial HTTP handshake
return token == "valid"
@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
if not valid:
await ws.close(code=1008)
return
await ws.accept()
while True:
msg = await ws.receive_text()
await ws.send_text(msg)База данных (SQLAlchemy)
Настройка SQLAlchemy
create_engine настраивает пул соединений БД; SessionLocal — фабрика сессий; Base — декларативная база моделей. Для SQLite с FastAPI задайте check_same_thread=False, так как запросы могут выполняться в разных потоках.
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base
SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"
engine = create_engine(
SQLALCHEMY_DATABASE_URL,
connect_args={"check_same_thread": False}, # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()Зависимость сессии
Зависимость с yield — канонический способ выдавать сессию БД: каждый запрос получает свежую сессию, закрываемую в блоке finally. Это гарантирует очистку, даже если маршрут бросил исключение.
from fastapi import Depends
from sqlalchemy.orm import Session
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
@app.get("/items")
def list_items(db: Session = Depends(get_db)):
return db.query(Item).all()
# each request gets its own session, closed automatically afterwardОпределение модели
Описывайте таблицы как ORM-модели SQLAlchemy, наследуясь от Base. В production используйте Alembic для миграций схемы, а не create_all(). Колонки могут иметь индексы, допускать NULL и значения по умолчанию на уровне БД или Python.
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base
Base = declarative_base()
class Item(Base):
__tablename__ = "items"
id = Column(Integer, primary_key=True, index=True)
name = Column(String, index=True, nullable=False)
price = Column(Integer, default=0)
in_stock = Column(Boolean, default=True)
# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)Создание записи
add() добавляет новую строку, commit() записывает её в БД, а refresh() перезагружает экземпляр с серверными значениями (например, автоинкрементным id). Оборачивайте несколько записей в транзакцию и коммитьте один раз в конце.
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session
app = FastAPI()
@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
item = Item(name=payload.name, price=payload.price)
db.add(item)
db.commit()
db.refresh(item) # load generated id
return itemВыборка записей
db.query(Model) начинает запрос; .filter() задаёт условия WHERE, .offset()/.limit() — пагинацию, .first() возвращает строку или None, .all() — список. Для простого равенства используйте .filter_by(name=x).
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
return db.query(Item).offset(skip).limit(limit).all()
@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemОбновление и удаление
Для частичного обновления перебирайте model_dump(exclude_unset=True), чтобы менялись только переданные поля. delete() помечает на удаление; commit() применяет. При успешном DELETE возвращайте 204 No Content.
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if not item:
raise HTTPException(status_code=404, detail="not found")
for k, v in payload.model_dump(exclude_unset=True).items():
setattr(item, k, v)
db.commit()
db.refresh(item)
return item
@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
item = db.query(Item).filter(Item.id == item_id).first()
if item:
db.delete(item)
db.commit()База данных (Tortoise ORM)
Настройка Tortoise
Tortoise ORM асинхронен по своей природе и хорошо сочетается с FastAPI. Инициализируйте его при старте с db_url и модулями моделей. generate_schemas() годится для разработки; в production используйте Aerich для миграций. В новом коде применяйте lifespan вместо on_event.
from fastapi import FastAPI
from tortoise import Tortoise
app = FastAPI()
async def init():
await Tortoise.init(
db_url="sqlite://db.sqlite3",
modules={"models": ["app.models"]},
)
await Tortoise.generate_schemas()
@app.on_event("startup")
async def startup():
await init()
@app.on_event("shutdown")
async def shutdown():
await Tortoise.close_connections()Определение модели
Модели Tortoise наследуются от Model и объявляют поля через tortoise.fields. Типы полей соответствуют типам колонок БД. Имя таблицы задаётся во вложенном классе Meta. Связи используют ForeignKeyField, ManyToManyField и т. д.
from tortoise import fields
from tortoise.models import Model
class Item(Model):
id = fields.IntField(pk=True)
name = fields.CharField(max_length=100)
price = fields.FloatField(default=0.0)
created_at = fields.DatetimeField(auto_now_add=True)
class Meta:
table = "items"
def __str__(self):
return self.nameСоздание записи
Item.create() — корутина, которая вставляет и возвращает новую строку. Чтобы вернуть ответ Pydantic, постройте BaseModel через from_tortoise_orm() (из tortoise.contrib.pydantic): так Tortoise корректно сериализует асинхронно загруженные связи.
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item
app = FastAPI()
class ItemIn(BaseModel):
name: str
price: float
@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
item = await Item.create(name=payload.name, price=payload.price)
return await ItemOut.from_tortoise_orm(item)Асинхронная выборка
Запросы Tortoise ожидаются: .all() возвращает queryset, .filter() добавляет условия, .get_or_none() берёт одну строку или None, .first() — первое совпадение. Избегайте .get(), если не ждёте ровно одну строку (иначе исключение).
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
return await Item.all().offset(skip).limit(limit)
@app.get("/items/{item_id}")
async def get_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
return itemОбновление и удаление
Измените атрибуты модели и вызовите await save(), чтобы обновить строку, или await Item.filter(id=...).update(name=x) для массового обновления. await item.delete() удаляет строку. Каждый метод — корутина, его нужно ожидать.
from fastapi import FastAPI, HTTPException
from .models import Item
app = FastAPI()
@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
item = await Item.get_or_none(id=item_id)
if not item:
raise HTTPException(status_code=404, detail="not found")
item.name = name
await item.save()
return item
@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
item = await Item.get_or_none(id=item_id)
if item:
await item.delete()Схемы Pydantic для Tortoise
tortoise.contrib.pydantic генерирует модели Pydantic прямо из моделей Tortoise, так что не нужно поддерживать две схемы. Используйте pydantic_model_creator для одного объекта и pydantic_queryset_creator для ответа-списка.
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item
ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)
@app.get("/items", response_model=ItemList)
async def list_items():
return await Item.all()
# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.Тестирование (TestClient)
Основы TestClient
TestClient оборачивает приложение и позволяет делать запросы в процессе (без реального сокета). Он основан на httpx и работает с pytest из коробки. Импортируйте тот же экземпляр app, что запускаете в production.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_root():
response = client.get("/")
assert response.status_code == 200
assert response.json() == {"Hello": "World"}
# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.Тесты GET и POST
Передавайте json= для JSON-тела, params= для query-параметров, headers= для заголовков и files= для multipart-загрузок. Ошибки валидации дают 422 — проверяйте status_code и структуру 'detail' в ошибке.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_create_item():
response = client.post(
"/items",
json={"name": "Apple", "price": 0.5},
)
assert response.status_code == 201
assert response.json()["name"] == "Apple"
def test_validation_error():
response = client.post("/items", json={"name": "Apple"}) # missing price
assert response.status_code == 422Фикстура pytest
Фикстура pytest, возвращающая TestClient, избавляет тесты от дублирования и даёт каждому тесту свежий клиент. Для тестов с БД добавьте фикстуру, которая создаёт и удаляет таблицы или откатывает транзакцию после каждого теста для изоляции.
import pytest
from fastapi.testclient import TestClient
from main import app
@pytest.fixture
def client():
return TestClient(app)
def test_read(client):
r = client.get("/items")
assert r.status_code == 200
def test_create(client):
r = client.post("/items", json={"name": "X"})
assert r.status_code == 201
# run: pytest -vПодмена зависимостей
app.dependency_overrides заменяет зависимость (например, реальную сессию БД или аутентификацию) на мок или фейк во время тестов, не меняя маршруты. Это канонический способ тестировать endpoint в изоляции от внешних сервисов. Очищайте подмены после тестов.
from fastapi.testclient import TestClient
from main import app, get_db
def get_test_db():
# return a test session or mock
yield FakeSession()
app.dependency_overrides[get_db] = get_test_db
client = TestClient(app)
def test_items():
r = client.get("/items")
assert r.status_code == 200
# restore afterwards:
app.dependency_overrides.clear()Тестирование аутентификации
OAuth2PasswordRequestForm ожидает form-encoded данные (data=, а не json=). Используйте полученный токен в заголовке Authorization: Bearer для последующих защищённых запросов. Чтобы полностью обойти аутентификацию, подмените зависимость get_current_user.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def get_token():
r = client.post(
"/token",
data={"username": "admin", "password": "secret"},
)
return r.json()["access_token"]
def test_protected():
token = get_token()
r = client.get(
"/me",
headers={"Authorization": f"Bearer {token}"},
)
assert r.status_code == 200
assert r.json()["username"] == "admin"Тестирование WebSocket
TestClient.websocket_connect() открывает WebSocket внутри менеджера контекста. Обменивайтесь сообщениями через send_text/receive_text (и варианты json/bytes). Приём на закрытом соединении бросает WebSocketDisconnect.
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_websocket():
with client.websocket_connect("/ws") as ws:
ws.send_text("hello")
data = ws.receive_text()
assert data == "echo: hello"
def test_websocket_close():
with client.websocket_connect("/ws") as ws:
ws.send_text("quit")
# the server closes the connectionДокументация OpenAPI
Swagger UI
FastAPI автоматически генерирует интерактивный Swagger UI на /docs по вашим маршрутам, типам и docstring. Задайте title/description/version у приложения и добавьте docstring или summary/description к каждому маршруту, чтобы обогатить интерфейс.
from fastapi import FastAPI
app = FastAPI(
title="My API",
description="Sample API with auto docs",
version="1.0.0",
)
@app.get("/items", summary="List items", description="Returns all items")
def list_items():
"""Get every item in the catalog."""
return [{"id": 1}]
# interactive docs at: http://localhost:8000/docsReDoc
ReDoc на /redoc — альтернатива Swagger только для чтения, ориентированная на документацию. Сырая схема OpenAPI доступна на /openapi.json и может передаваться другим инструментам. Отключить документацию можно через docs_url=None, redoc_url=None, openapi_url=None (например, в production).
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def root():
return {"hello": "world"}
# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json
# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)Теги и группировка
Теги группируют маршруты в интерфейсе документации. Заранее объявите метаданные тегов (name, description, externalDocs) в openapi_tags, чтобы группа появилась ещё до использования. deprecated=True помечает endpoint устаревшим в документации.
from fastapi import FastAPI
app = FastAPI(openapi_tags=[
{"name": "users", "description": "User management"},
{"name": "items", "description": "Item operations"},
])
@app.get("/users", tags=["users"])
def list_users(): ...
@app.post("/items", tags=["items"])
def create_item(): ...
@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...Метаданные маршрута
Декораторы принимают метаданные, попадающие в OpenAPI: summary (короткий заголовок), description (длинный текст), response_description, tags, deprecated и status_code. Docstring используется как description, если не передать его явно.
from fastapi import FastAPI, status
from pydantic import BaseModel
class Item(BaseModel):
name: str
price: float
app = FastAPI()
@app.post(
"/items",
response_model=Item,
status_code=status.HTTP_201_CREATED,
summary="Create an item",
description="Creates a new item and returns it.",
tags=["items"],
response_description="The created item",
)
def create_item(item: Item):
"""Create endpoint docstring — also shown in docs."""
return itemПримеры полей
Field(examples=[...]) и Body(examples=[...]) добавляют примеры в 'Try it out' Swagger UI и выпадающий список примеров. Примеры тела могут содержать несколько случаев с описаниями, показывая валидный и невалидный ввод.
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body
class Item(BaseModel):
name: str = Field(examples=["Apple"])
price: float = Field(examples=[0.5], gt=0)
app = FastAPI()
@app.post("/items")
def create_item(item: Item):
return item
@app.post("/manual")
def manual(
item: Item = Body(
examples=[
{"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
{"summary": "invalid", "value": {"name": "Apple", "price": -1}},
],
),
):
return itemСвоя схема OpenAPI
Переопределите app.openapi, чтобы изменить генерируемую схему: добавить логотип, лишние метаданные или убрать и преобразовать операции. Кешируйте результат в app.openapi_schema, чтобы схема генерировалась один раз. Именно её отдаёт /openapi.json.
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi
app = FastAPI()
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
schema = get_openapi(
title="Custom API",
version="2.0.0",
routes=app.routes,
)
schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
app.openapi_schema = schema
return schema
app.openapi = custom_openapiРазвёртывание (Uvicorn / Gunicorn)
Uvicorn в production
В production запускайте Uvicorn за обратным прокси (Nginx, Caddy, облачный балансировщик). Используйте --proxy-headers, чтобы приложение видело реальный IP и хост клиента из X-Forwarded-For/X-Forwarded-Proto. Не используйте --reload в production.
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1
# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'Gunicorn с воркерами Uvicorn
Gunicorn управляет несколькими процессами-воркерами Uvicorn: даёт плавную перезагрузку, перезапуск при падении и pre-fork масштабирование. Используйте класс UvicornWorker. Начните с числа воркеров (2 * число ядер + 1), затем измеряйте производительность.
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn
# run 4 worker processes managed by gunicorn
gunicorn main:app \
-w 4 \
-k uvicorn.workers.UvicornWorker \
-b 0.0.0.0:8000 \
--timeout 120
# -w workers (commonly 2*CPU+1), -k worker classРазвёртывание в Docker
Тонкий базовый образ Python уменьшает размер образа. Устанавливайте зависимости до копирования кода, чтобы использовать кеш слоёв Docker. Внутри контейнера запускайте воркеры gunicorn+uvicorn и откройте порт 8000 для хоста или оркестратора.
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
"-k", "uvicorn.workers.UvicornWorker", \
"-b", "0.0.0.0:8000"]
# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapiКонфигурация окружения
pydantic-settings (ранее pydantic.BaseSettings) загружает конфигурацию из переменных окружения и файлов .env с проверкой типов. Так один и тот же образ работает в разных окружениях (dev/staging/prod), достаточно изменить переменные окружения.
import os
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
database_url: str = "sqlite:///./app.db"
secret_key: str = "change-me"
debug: bool = False
allowed_origins: list[str] = ["http://localhost:3000"]
class Config:
env_file = ".env"
env_file_encoding = "utf-8"
settings = Settings()
# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=falseОбратный прокси Nginx
Nginx принимает HTTP(S) и передаёт на Uvicorn на localhost:8000. Задайте заголовки X-Forwarded-* (и использу йте --proxy-headers в Uvicorn), чтобы приложение видело реальный IP и схему клиента. Строки Upgrade/Connection включают поддержку WebSocket.
# /etc/nginx/conf.d/api.conf
server {
listen 80;
server_name api.example.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host \$host;
proxy_set_header X-Real-IP \$remote_addr;
proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto \$scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade \$http_upgrade;
proxy_set_header Connection "upgrade";
}
}Масштабирование и конкурентность
Масштабируйте двумя способами: больше воркеров Uvicorn на машине (CPU-нагрузка) и больше машин за балансировщиком (горизонтально). В асинхронных приложениях цикл событий обрабатывает много одновременных I/O-запросов на воркер. Добавьте endpoint /health, чтобы оркестраторы (k8s, ECS) проверяли живость.
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.
# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.
# Health check endpoint for the balancer:
@app.get("/health")
def health():
return {"status": "ok"}Продвинутые темы
События lifespan
Контекстный менеджер lifespan заменяет устаревшие обработчики on_event('startup'/'shutdown'). Код до yield выполняется при старте, после yield — при остановке, даже если старт не удался. Используйте его для инициализации подключений к БД, ML-моделей и кешей.
from contextlib import asynccontextmanager
from fastapi import FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
# runs at startup
print("starting up")
app.state.cache = {}
yield
# runs at shutdown
print("shutting down")
await app.state.cache.clear()
app = FastAPI(lifespan=lifespan)
# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.Подприложения (mount)
app.mount() присоединяет подприложение под префиксом пути — удобно для версионированных API или объединения нескольких приложений. У каждого подприложения свои маршруты и схема OpenAPI; документация родителя по умолчанию не включает маршруты дочернего.
from fastapi import FastAPI
app = FastAPI()
api_v1 = FastAPI()
api_v2 = FastAPI()
@api_v1.get("/items")
def v1_items():
return {"version": 1}
@api_v2.get("/items")
def v2_items():
return {"version": 2}
app.mount("/v1", api_v1)
app.mount("/v2", api_v2)
# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}APIRouter
APIRouter группирует связанные маршруты в модуль с общим префиксом, тегами, зависимостями и ответами. Подключайте через app.include_router(router) (при желании со своим префиксом или тегами). Это стандартный паттерн структурирования нетривиальных приложений.
from fastapi import APIRouter, Depends
router = APIRouter(
prefix="/items",
tags=["items"],
dependencies=[Depends(verify_token)],
responses={404: {"description": "Not found"}},
)
@router.get("/")
def list_items():
return []
@router.get("/{item_id}")
def get_item(item_id: int):
return {"id": item_id}
# in main.py: app.include_router(router)Статические файлы
StaticFiles отдаёт каталог статических ресурсов (изображения, CSS, JS) по URL-префиксу. Монтируйте его один раз на каталог. Для SPA-фронтендов смонтируйте финальный catch-all маршрут на index.html. Статические файлы обходят систему маршрутизации ради скорости.
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles
app = FastAPI()
# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")
# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.cssПотоковый ответ
StreamingResponse отправляет ответ, генерируемый частями (генератор или итератор), вместо сборки всего тела в памяти — идеально для больших экспортов CSV, потоковой передачи файлов и SSE. Задайте подходящий media_type, чтобы клиенты правильно обрабатывали поток.
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io
app = FastAPI()
def iter_csv():
output = io.StringIO()
writer = csv.writer(output)
writer.writerow(["id", "name"])
for i in range(1000):
writer.writerow([i, f"name-{i}"])
yield output.getvalue()
output.seek(0)
output.truncate(0)
@app.get("/export.csv")
def export():
return StreamingResponse(
iter_csv(),
media_type="text/csv",
headers={"Content-Disposition": "attachment; filename=export.csv"},
)Свой класс маршрута
Наследование от APIRoute позволяет обернуть каждый обработчик своей логикой (логирование, трассировка, замеры времени), не трогая endpoint. Задайте app.router.route_class или передайте route_class в APIRouter. Обработчик выполняется для каждого подходящего запроса.
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable
class LoggingRoute(APIRoute):
def get_route_handler(self) -> Callable:
original = super().get_route_handler()
async def handler(request: Request) -> Response:
print(f"-> {request.method} {request.url.path}")
response = await original(request)
print(f"<- {response.status_code}")
return response
return handler
app = FastAPI()
app.router.route_class = LoggingRoute
@app.get("/items")
def items():
return {"items": []}Связанные сниппеты FastAPI
Copy-paste ready code for common tasks.
Path Parameters
Capture typed path segments with validation.
Query Parameters
Parse query strings with defaults and validation.
Pydantic Request Body
Validate JSON bodies with Pydantic models.
Dependency Injection
Share logic via Depends and yield-based dependencies.
Response Model
Shape and filter responses with response_model.
JWT Auth
Issue and verify JSON Web Tokens with OAuth2.
Async and Await
Define async handlers and run blocking work in a thread.
Middleware
Add CORS, timing, and custom middleware.
Was this helpful?