FastAPI: зависимости и база данных

`Depends` и дерево зависимостей, одна сессия SQLAlchemy на запрос через зависимость с `yield`, CRUD со схемами Pydantic, коды состояния и `HTTPException`, роутеры, async и фоновые задачи, тесты с `TestClient` и временной базой.

  • Продвинутый
  • 25 мин
  • 12 вопросов
  • Урок 46 из 66

В этом уроке ты узнаешь

  • Строить зависимости и деревья зависимостей через Depends и объяснять их кеш в пределах запроса
  • Открывать и закрывать одну сессию SQLAlchemy на запрос через зависимость с yield
  • Писать CRUD-эндпоинты со схемами Pydantic, response_model, правильными кодами состояния и HTTPException
  • Тестировать API с TestClient, dependency_overrides и временной базой

В уроке «Веб-сервис на 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).

  1. Находится маршрут

    FastAPI сопоставляет путь и метод с эндпоинтом.

  2. Решаются зависимости

    Дерево решается от листьев вверх, каждая зависимость — один раз; проверяются параметры и тело. HTTPException из зависимости или ошибка проверки (422) останавливают запрос здесь.

  3. Работает эндпоинт

    Функция получает готовые значения как аргументы.

  4. Ответ и уборка

    Результат фильтруется через response_model, превращается в JSON и отправляется; затем выполняется часть finally зависимостей с yield.

Python
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}
FastAPI не работает в браузере — запускай код на своём компьютере после pip install "fastapi[standard]" sqlalchemy. Header() сопоставляет имя параметра x_token заголовку X-Token. Параметр запроса limit=5 дошёл до зависимости (pagination).

Чтобы читать дальше, зарегистрируйся бесплатно

Остальные разделы урока, тест и заметки открываются с аккаунтом Educora. Регистрация занимает минуту, а прогресс сохраняется на всех твоих устройствах.

Одна сессия на запрос

Зависимость может использовать yield вместо return. Тогда часть до yield выполняется до эндпоинта, а часть в блоке finally — после того, как ответ готов, даже после ошибки. Это та же идея, что with из урока «Контекстные менеджеры и оператор with», и она идеальна для подключения к базе. И ещё: если в одном запросе зависимость используется в нескольких местах, FastAPI вызывает её один раз и запоминает результат.

Python
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 по умолчанию разрешает использовать подключение только в том потоке, который его создал.

Python
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-объекта.

Python
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.
Python
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: bool
schemas.py — входные и выходные схемы API.
Python
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» не повторяется в трёх эндпоинтах.
Python
@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 task
main.py, часть 2: создание, список и одна задача. response_model=TaskRead превращает ORM-объект в схему и не пускает в ответ поля, которых нет в схеме (например, будущий owner_password_hash). Query(le=100) ограничивает размер страницы.
Python
@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 /tasks201 Created422 — тело не подходит к схеме
GET /tasks?skip=0&limit=20200 OK422 — limit > 100
GET /tasks/{task_id}200 OK404 — задачи нет
PATCH /tasks/{task_id}200 OK404 / 422
DELETE /tasks/{task_id}204 — без тела404
Python
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 required
Запущено на пустой базе. PATCH изменил только done, заголовок остался. У ответа 204 пустое тело. Ошибки Pydantic показывают в списке detail место (loc) и причину (msg).

Роутеры, async и фоновые задачи

Когда эндпоинтов становится много, их раскладывают по файлам по темам: APIRouter(prefix='/tasks', tags=['tasks']) похож на blueprint во Flask и подключается через app.include_router(router); tags создают группы на странице /docs. BackgroundTasks выполняет небольшую работу (письмо, запись в журнал) после отправки ответа — клиент её не ждёт. Долгие и важные задачи выносят в отдельную очередь (Celery, RQ).

Python
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']
202 Accepted означает «принято, будет выполнено позже». TestClient выполняет фоновую задачу после ответа, но до возврата из post(), поэтому журнал уже заполнен.

Тесты с TestClient и временной базой

Главное преимущество зависимостей видно в тестах: app.dependency_overrides[get_db] = override_get_db подменяет настоящую базу другой на время тестов, не трогая код. База SQLite в памяти (sqlite://) при каждом запуске тестов начинается с чистого листа. Но база в памяти привязана к подключению, поэтому используем StaticPool: все сессии делят одно подключение и видят одни и те же таблицы. Тесты пишем с assert, как в уроке «Тестирование с pytest».

Python
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: временная база и подмена зависимости.
Python
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.
Terminal
python -m pytest -q test_main.py

Ожидаемый результат

...                                                                      [100%]
3 passed in 1.20s
Каждая точка — пройденный тест; время каждый раз своё. Новые версии Starlette могут ещё напечатать предупреждение об HTTP-библиотеке тестового клиента — на результат это не влияет.

Задание

Напиши мини-Depends: solve(func) должна смотреть на параметры функции (inspect.signature) и для каждого параметра со значением по умолчанию Depends(dep) сначала (рекурсивно) решать dep и передавать результат. Как в FastAPI, в пределах одного «запроса» каждая зависимость вызывается только один раз (cache).

Задание · Python
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.

Задание · Python
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 + finally get_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.
Заметил ошибку или неточность в уроке?

Проверь себя

Вопросов: 12. Каждый правильный ответ приносит XP.

Вопрос 1 / 12

Вопрос 1 / 12. Что означает db: Annotated[Session, Depends(get_db)] в параметрах эндпоинта?