В уроке «Веб-сервис на FastAPI» задачи хранились в словаре в памяти: при перезапуске сервера всё пропадало. Настоящее API хранит данные в базе и в каждом запросе делает одни и те же дела: подключается к базе, проверяет пользователя, читает параметры постраничного вывода. Вместо того чтобы копировать эти повторяющиеся куски в каждую функцию, FastAPI использует зависимости (dependency injection). В этом уроке разберём Depends, одну сессию SQLAlchemy на запрос, CRUD со схемами Pydantic, ошибки и тесты с временной базой.
Зависимости: Depends
Зависимость (dependency)Определение
Значение, которое нужно эндпоинту и которое FastAPI сам готовит и передаёт. Если в параметре написано Depends(функция), FastAPI при каждом запросе вызывает эту функцию и кладёт её результат в параметр. У зависимости могут быть свои параметры (параметры запроса, заголовки и другие зависимости) — так получается дерево зависимостей.
В примере ниже эндпоинт lessons зависит от двух вещей: параметров постраничного вывода и текущего пользователя. current_user, в свою очередь, зависит от get_token, который читает заголовок X-Token. Если токен неверный, HTTPException(401) останавливает запрос, не доходя до эндпоинта. Запись Annotated[тип, Depends(...)] держит тип и зависимость вместе, и её можно превратить в псевдоним для повторного использования (например, SessionDep).
Находится маршрут
FastAPI сопоставляет путь и метод с эндпоинтом.
Решаются зависимости
Дерево решается от листьев вверх, каждая зависимость — один раз; проверяются параметры и тело.
HTTPExceptionиз зависимости или ошибка проверки (422) останавливают запрос здесь.Работает эндпоинт
Функция получает готовые значения как аргументы.
Ответ и уборка
Результат фильтруется через
response_model, превращается в JSON и отправляется; затем выполняется частьfinallyзависимостей сyield.
from typing import Annotated
from fastapi import Depends, FastAPI, Header, HTTPException
from fastapi.testclient import TestClient
app = FastAPI()
def pagination(skip: int = 0, limit: int = 10):
return {'skip': skip, 'limit': limit}
def get_token(x_token: Annotated[str | None, Header()] = None):
if x_token != 'secret-token':
raise HTTPException(status_code=401, detail='Invalid token')
return x_token
def current_user(token: Annotated[str, Depends(get_token)]):
return {'name': 'Aysel', 'role': 'teacher'}
@app.get('/lessons')
def lessons(page: Annotated[dict, Depends(pagination)],
user: Annotated[dict, Depends(current_user)]):
return {'user': user['name'], **page}
client = TestClient(app)
r = client.get('/lessons', params={'limit': 5})
print(r.status_code, r.json())
r = client.get('/lessons', params={'limit': 5}, headers={'X-Token': 'secret-token'})
print(r.status_code, r.json())Ожидаемый результат
401 {'detail': 'Invalid token'}
200 {'user': 'Aysel', 'skip': 0, 'limit': 5}pip install "fastapi[standard]" sqlalchemy. Header() сопоставляет имя параметра x_token заголовку X-Token. Параметр запроса limit=5 дошёл до зависимости (pagination).Чтобы читать дальше, зарегистрируйся бесплатно
Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.
Одна сессия на запрос
Зависимость может использовать yield вместо return. Тогда часть до yield выполняется до эндпоинта, а часть в блоке finally — после того, как ответ готов, даже после ошибки. Это та же идея, что with из урока «Контекстные менеджеры и оператор with», и она идеальна для подключения к базе. И ещё: если в одном запросе зависимость используется в нескольких местах, FastAPI вызывает её один раз и запоминает результат.
from typing import Annotated
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
app = FastAPI()
calls = []
def get_resource():
print('open resource')
try:
yield {'id': len(calls) + 1}
finally:
print('close resource')
def counter(res: Annotated[dict, Depends(get_resource)]):
calls.append(res)
return len(calls)
@app.get('/use')
def use(res: Annotated[dict, Depends(get_resource)], n: Annotated[int, Depends(counter)]):
print('endpoint got', res, 'call', n)
return {'ok': True}
client = TestClient(app)
print(client.get('/use').json())Ожидаемый результат
open resource
endpoint got {'id': 1} call 1
close resource
{'ok': True}get_resource нужна и эндпоинту, и counter, но «open resource» напечатано один раз — кеш в пределах запроса. «close resource» идёт после эндпоинта.Теперь настоящий слой данных. В database.py лежат движок (см. «SQLAlchemy: базы данных через ORM»), фабрика сессий SessionLocal и зависимость get_db: каждый запрос получает свою сессию и в конце закрывает её. check_same_thread=False нужен, потому что FastAPI выполняет обычные def-эндпоинты в рабочих потоках, а SQLite по умолчанию разрешает использовать подключение только в том потоке, который его создал.
from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, sessionmaker
DATABASE_URL = 'sqlite:///./tasks.db'
engine = create_engine(DATABASE_URL, connect_args={'check_same_thread': False})
SessionLocal = sessionmaker(bind=engine, autoflush=False)
class Base(DeclarativeBase):
pass
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()database.py.CRUD со схемами Pydantic
Модель SQLAlchemy описывает таблицу в базе, а схема Pydantic — «договор» API (см. «Pydantic: валидация данных»). Разделять их важно: TaskCreate — поля, которые может прислать клиент (id нет — его даёт база), в TaskUpdate все поля необязательны (PATCH присылает только то, что меняется), а TaskRead определяет, что попадёт в ответ. from_attributes=True позволяет строить схему из атрибутов ORM-объекта.
from sqlalchemy import String
from sqlalchemy.orm import Mapped, mapped_column
from database import Base
class Task(Base):
__tablename__ = 'tasks'
id: Mapped[int] = mapped_column(primary_key=True)
title: Mapped[str] = mapped_column(String(100))
subject: Mapped[str] = mapped_column(String(30), default='python')
done: Mapped[bool] = mapped_column(default=False)models.py — модель SQLAlchemy.from pydantic import BaseModel, ConfigDict, Field
class TaskCreate(BaseModel):
title: str = Field(min_length=1, max_length=100)
subject: str = 'python'
class TaskUpdate(BaseModel):
title: str | None = Field(default=None, min_length=1, max_length=100)
done: bool | None = None
class TaskRead(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
title: str
subject: str
done: boolschemas.py — входные и выходные схемы API.from typing import Annotated
from fastapi import Depends, FastAPI, HTTPException, Query, status
from sqlalchemy import select
from sqlalchemy.orm import Session
from database import Base, engine, get_db
from models import Task
from schemas import TaskCreate, TaskRead, TaskUpdate
Base.metadata.create_all(engine)
app = FastAPI(title='Tasks API')
SessionDep = Annotated[Session, Depends(get_db)]
def get_task_or_404(task_id: int, db: SessionDep) -> Task:
task = db.get(Task, task_id)
if task is None:
raise HTTPException(status_code=404, detail='Task not found')
return task
TaskDep = Annotated[Task, Depends(get_task_or_404)]main.py, часть 1. get_task_or_404 сама является зависимостью: берёт параметр пути task_id и сессию и выбрасывает 404, если задачи нет. Так логика «найти или 404» не повторяется в трёх эндпоинтах.@app.post('/tasks', response_model=TaskRead, status_code=status.HTTP_201_CREATED)
def create_task(data: TaskCreate, db: SessionDep):
task = Task(**data.model_dump())
db.add(task)
db.commit()
db.refresh(task)
return task
@app.get('/tasks', response_model=list[TaskRead])
def list_tasks(db: SessionDep, skip: int = 0, limit: Annotated[int, Query(le=100)] = 20):
stmt = select(Task).order_by(Task.id).offset(skip).limit(limit)
return db.scalars(stmt).all()
@app.get('/tasks/{task_id}', response_model=TaskRead)
def read_task(task: TaskDep):
return taskmain.py, часть 2: создание, список и одна задача. response_model=TaskRead превращает ORM-объект в схему и не пускает в ответ поля, которых нет в схеме (например, будущий owner_password_hash). Query(le=100) ограничивает размер страницы.@app.patch('/tasks/{task_id}', response_model=TaskRead)
def update_task(data: TaskUpdate, task: TaskDep, db: SessionDep):
for field, value in data.model_dump(exclude_unset=True).items():
setattr(task, field, value)
db.commit()
db.refresh(task)
return task
@app.delete('/tasks/{task_id}', status_code=status.HTTP_204_NO_CONTENT)
def delete_task(task: TaskDep, db: SessionDep):
db.delete(task)
db.commit()main.py, часть 3. exclude_unset=True отдаёт только поля, которые клиент действительно прислал; без него неприсланный title стал бы None, и база выдала бы ошибку NOT NULL. TaskDep и SessionDep в одном запросе получают одну и ту же сессию (кеш зависимостей), поэтому найденный объект можно изменить и закоммитить.| Запрос | Успех | Ошибка |
|---|---|---|
POST /tasks | 201 Created | 422 — тело не подходит к схеме |
GET /tasks?skip=0&limit=20 | 200 OK | 422 — limit > 100 |
GET /tasks/{task_id} | 200 OK | 404 — задачи нет |
PATCH /tasks/{task_id} | 200 OK | 404 / 422 |
DELETE /tasks/{task_id} | 204 — без тела | 404 |
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
r = client.post('/tasks', json={'title': 'Learn Depends'})
print(r.status_code, r.json())
client.post('/tasks', json={'title': 'Revise SQL', 'subject': 'sql'})
print(client.get('/tasks', params={'skip': 1}).json())
print(client.patch('/tasks/1', json={'done': True}).json())
r = client.delete('/tasks/2')
print(r.status_code, r.content)
r = client.get('/tasks/2')
print(r.status_code, r.json())
r = client.get('/tasks', params={'limit': 500})
print(r.status_code, r.json()['detail'][0]['msg'])
r = client.post('/tasks', json={'subject': 'sql'})
print(r.status_code, r.json()['detail'][0]['loc'], r.json()['detail'][0]['msg'])Ожидаемый результат
201 {'id': 1, 'title': 'Learn Depends', 'subject': 'python', 'done': False}
[{'id': 2, 'title': 'Revise SQL', 'subject': 'sql', 'done': False}]
{'id': 1, 'title': 'Learn Depends', 'subject': 'python', 'done': True}
204 b''
404 {'detail': 'Task not found'}
422 Input should be less than or equal to 100
422 ['body', 'title'] Field requireddone, заголовок остался. У ответа 204 пустое тело. Ошибки Pydantic показывают в списке detail место (loc) и причину (msg).Роутеры, async и фоновые задачи
Когда эндпоинтов становится много, их раскладывают по файлам по темам: APIRouter(prefix='/tasks', tags=['tasks']) похож на blueprint во Flask и подключается через app.include_router(router); tags создают группы на странице /docs. BackgroundTasks выполняет небольшую работу (письмо, запись в журнал) после отправки ответа — клиент её не ждёт. Долгие и важные задачи выносят в отдельную очередь (Celery, RQ).
from fastapi import APIRouter, BackgroundTasks, FastAPI
from fastapi.testclient import TestClient
router = APIRouter(prefix='/reports', tags=['reports'])
log = []
def write_log(message: str):
log.append(message)
@router.post('/{report_id}/send', status_code=202)
def send_report(report_id: int, background: BackgroundTasks):
background.add_task(write_log, f'report {report_id} sent')
return {'status': 'queued'}
app = FastAPI()
app.include_router(router)
client = TestClient(app)
print(client.post('/reports/7/send').json(), log)
print(list(app.openapi()['paths']))Ожидаемый результат
{'status': 'queued'} ['report 7 sent']
['/reports/{report_id}/send']TestClient выполняет фоновую задачу после ответа, но до возврата из post(), поэтому журнал уже заполнен.Тесты с TestClient и временной базой
Главное преимущество зависимостей видно в тестах: app.dependency_overrides[get_db] = override_get_db подменяет настоящую базу другой на время тестов, не трогая код. База SQLite в памяти (sqlite://) при каждом запуске тестов начинается с чистого листа. Но база в памяти привязана к подключению, поэтому используем StaticPool: все сессии делят одно подключение и видят одни и те же таблицы. Тесты пишем с assert, как в уроке «Тестирование с pytest».
from fastapi.testclient import TestClient
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool
from database import Base, get_db
from main import app
engine = create_engine('sqlite://', connect_args={'check_same_thread': False},
poolclass=StaticPool)
TestingSession = sessionmaker(bind=engine)
Base.metadata.create_all(engine)
def override_get_db():
db = TestingSession()
try:
yield db
finally:
db.close()
app.dependency_overrides[get_db] = override_get_db
client = TestClient(app)test_main.py, часть 1: временная база и подмена зависимости.def test_create_and_read():
r = client.post('/tasks', json={'title': 'Write tests'})
assert r.status_code == 201
task_id = r.json()['id']
assert client.get(f'/tasks/{task_id}').json()['title'] == 'Write tests'
def test_update_only_sent_fields():
task_id = client.post('/tasks', json={'title': 'Old title'}).json()['id']
r = client.patch(f'/tasks/{task_id}', json={'done': True})
assert r.json()['title'] == 'Old title' and r.json()['done'] is True
def test_missing_task_is_404():
r = client.get('/tasks/999')
assert r.status_code == 404
assert r.json() == {'detail': 'Task not found'}test_main.py, часть 2: три теста. Второй проверяет, что PATCH не трогает неприсланное поле, — именно такой тест ловит забытый exclude_unset.python -m pytest -q test_main.pyОжидаемый результат
... [100%] 3 passed in 1.20s
Задание
Напиши мини-Depends: solve(func) должна смотреть на параметры функции (inspect.signature) и для каждого параметра со значением по умолчанию Depends(dep) сначала (рекурсивно) решать dep и передавать результат. Как в FastAPI, в пределах одного «запроса» каждая зависимость вызывается только один раз (cache).
import inspect
class Depends:
def __init__(self, dependency):
self.dependency = dependency
def solve(func, cache=None):
# for every parameter with a Depends default: solve it once (use cache), then call func(**kwargs)
return func()
calls = []
def get_settings():
calls.append('settings')
return {'db_url': 'sqlite://'}
def get_db(settings=Depends(get_settings)):
calls.append('db')
return f"session({settings['db_url']})"
def get_repo(db=Depends(get_db), settings=Depends(get_settings)):
calls.append('repo')
return f'repo with {db}'
def endpoint(repo=Depends(get_repo), db=Depends(get_db)):
return f'{repo}; {db}'
print(solve(endpoint))
print(calls)Ожидаемый результат
repo with session(sqlite://); session(sqlite://) ['settings', 'db', 'repo']
Задание
Повтори, как работает зависимость с yield: run(endpoint, *args) запускает генератор get_db(), берёт «сессию» через next(), вызывает эндпоинт и возвращает (200, результат); при HTTPError возвращает (status, {'detail': ...}). В любом случае в конце закрывает генератор, чтобы сработал finally.
class HTTPError(Exception):
def __init__(self, status, detail):
self.status, self.detail = status, detail
log = []
def get_db():
log.append('open')
try:
yield {'tasks': {1: 'Learn Depends'}}
finally:
log.append('close')
def read_task(db, task_id):
if task_id not in db['tasks']:
raise HTTPError(404, 'Task not found')
return db['tasks'][task_id]
def run(endpoint, *args):
# gen = get_db(); db = next(gen); try / except HTTPError / finally: gen.close()
return None
print(run(read_task, 1))
print(run(read_task, 5))
print(log)Ожидаемый результат
(200, 'Learn Depends')
(404, {'detail': 'Task not found'})
['open', 'close', 'open', 'close']Запомни
Depends(f)велит FastAPI вызыватьfпри каждом запросе и передавать результат; у зависимостей бывают свои зависимости, и каждая решается один раз за запрос.- С
yield+finallyget_dbоткрывает сессию до запроса и обязательно закрывает после; псевдонимыAnnotated(SessionDep) убирают повторы. - Модель ≠ схема:
TaskCreate/TaskUpdate/TaskRead;response_modelфильтрует ответ, в PATCH —exclude_unset=True. - 201 при создании, 204 при удалении, 404 через
HTTPException, 422 при ошибке проверки; роутеры делят эндпоинты по файлам. - В тестах:
app.dependency_overrides[get_db]+sqlite://+StaticPool; блокирующий код — вdef, а вasync def— толькоawait.