FastAPI: asılılıqlar və verilənlər bazası

`Depends` və asılılıqlar ağacı, `yield`-li asılılıqla sorğu başına bir SQLAlchemy sessiyası, Pydantic sxemləri ilə CRUD, status kodları və `HTTPException`, routerlər, async və arxa fon işləri, `TestClient` və müvəqqəti bazalı testlər.

  • İrəli
  • 25 dəq
  • 12 sual
  • 66 dərsdən 46-cısı

Bu dərsdə öyrənəcəksən

  • Depends ilə asılılıqlar və asılılıqlar ağacı qurmaq, onların sorğu daxilində keşini izah etmək
  • yield-li asılılıqla sorğu başına bir SQLAlchemy sessiyası açıb bağlamaq
  • Pydantic sxemləri, response_model, düzgün status kodları və HTTPException ilə CRUD endpoint-ləri yazmaq
  • API-ni TestClient, dependency_overrides və müvəqqəti baza ilə test etmək

«FastAPI ilə veb servis» dərsində tapşırıqlar yaddaşdakı lüğətdə saxlanılırdı: server yenidən başlayanda hamısı itirdi. Real API məlumatı bazada saxlayır və hər sorğuda eyni işləri görür: bazaya qoşulur, istifadəçini yoxlayır, səhifələmə parametrlərini oxuyur. Bu təkrarlanan hissələri hər funksiyaya köçürmək əvəzinə FastAPI asılılıqlardan (dependency injection) istifadə edir. Bu dərsdə Depends-i, sorğu başına bir SQLAlchemy sessiyasını, Pydantic sxemləri ilə CRUD-u, xətaları və müvəqqəti bazalı testləri öyrənəcəyik.

Asılılıqlar: Depends

Asılılıq (dependency)Tərif

Endpoint-in işləməsi üçün lazım olan və FastAPI-nin özü hazırlayıb ötürdüyü dəyər. Parametrdə Depends(funksiya) yazanda FastAPI hər sorğuda həmin funksiyanı çağırır, onun nəticəsini parametrə qoyur. Asılılığın da öz parametrləri (sorğu parametrləri, başlıqlar və başqa asılılıqlar) ola bilər — beləcə asılılıqlar ağacı yaranır.

Aşağıdakı nümunədə lessons endpoint-i iki şeydən asılıdır: səhifələmə parametrlərindən və cari istifadəçidən. current_user isə öz növbəsində get_token-dən asılıdır, o da X-Token başlığını oxuyur. Token səhvdirsə, HTTPException(401) endpoint-ə çatmadan sorğunu dayandırır. Annotated[tip, Depends(...)] yazılışı tipi və asılılığı bir yerdə saxlayır, onu ləqəbə (SessionDep kimi) çevirib təkrar istifadə etmək olur.

  1. Marşrut tapılır

    FastAPI yolu və metodu uyğun endpoint-ə bağlayır.

  2. Asılılıqlar həll olunur

    Ağac yarpaqlardan yuxarı həll olunur, hər asılılıq bir dəfə; parametrlər və gövdə yoxlanılır. Asılılığın HTTPException-ı və ya yoxlama xətası (422) sorğunu burada dayandırır.

  3. Endpoint işləyir

    Funksiya hazır dəyərləri arqument kimi alır.

  4. Cavab və təmizlik

    Nəticə response_model ilə süzülüb JSON-a çevrilir və göndərilir; sonra yield-li asılılıqların finally hissəsi işləyir.

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())

Gözlənilən nəticə

401 {'detail': 'Invalid token'}
200 {'user': 'Aysel', 'skip': 0, 'limit': 5}
FastAPI brauzerdə işləmir — kodu öz kompüterində pip install "fastapi[standard]" sqlalchemy əmrindən sonra icra et. Header() parametri x_token adını X-Token başlığına çevirir. limit=5 sorğu parametri asılılığa (pagination) çatıb.

Davamını oxumaq üçün pulsuz qeydiyyatdan keç

Dərsin qalan bölmələri, test və qeydlər Educora hesabı ilə açılır. Qeydiyyat bir dəqiqə çəkir; irəliləyişin bütün cihazlarında saxlanılır.

Sorğu başına bir sessiya

Asılılıq return əvəzinə yield istifadə edə bilər. Onda yield-ə qədərki hissə endpoint-dən əvvəl, finally blokundakı hissə isə cavab hazır olandan sonra işləyir — xəta olsa belə. Bu, «Kontekst menecerləri və with operatoru» dərsindəki with-in eyni ideyasıdır və bazaya qoşulma üçün idealdır. Bir də: eyni sorğuda bir asılılıq bir neçə yerdə istifadə olunsa, FastAPI onu bir dəfə çağırır və nəticəni yadda saxlayır.

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())

Gözlənilən nəticə

open resource
endpoint got {'id': 1} call 1
close resource
{'ok': True}
get_resource həm endpoint-də, həm də counter-də lazımdır, amma «open resource» bir dəfə çap olunub — sorğu daxilində keş. «close resource» endpoint-dən sonra gəlir.

İndi real baza qatı. database.py mühərriki (bax: «SQLAlchemy: ORM ilə verilənlər bazası»), sessiya fabriki SessionLocal-u və get_db asılılığını saxlayır: hər sorğu öz sessiyasını alır və sonda onu bağlayır. check_same_thread=False lazımdır, çünki FastAPI adi def endpoint-lərini ayrıca axınlarda (thread) icra edir, SQLite isə standart olaraq qoşulmanı yalnız onu yaradan axında istifadə etməyə icazə verir.

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.

Pydantic sxemləri ilə CRUD

SQLAlchemy modeli bazadakı cədvəli, Pydantic sxemi isə API-nin «müqaviləsini» təsvir edir (bax: «Pydantic: verilənlərin yoxlanması»). Onları ayırmaq vacibdir: TaskCreate müştərinin göndərə biləcəyi sahələrdir (id yoxdur — onu baza verir), TaskUpdate-də bütün sahələr seçimlidir (PATCH yalnız dəyişəni göndərir), TaskRead isə cavabda nəyin görünəcəyini müəyyən edir. from_attributes=True sxemi ORM obyektinin atributlarından qurmağa imkan verir.

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 modeli.
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-nin giriş və çıxış sxemləri.
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-ci hissə. get_task_or_404 özü də asılılıqdır: yolun task_id parametrini və sessiyanı alır, tapşırığı tapmasa 404 qaldırır. Beləliklə «tap və ya 404» məntiqi üç endpoint-də təkrarlanmır.
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-ci hissə: yaratmaq, siyahı və bir tapşırıq. response_model=TaskRead ORM obyektini sxemə çevirir və sxemdə olmayan sahələri (məsələn, gələcəkdə owner_password_hash) cavabdan kənarda saxlayır. Query(le=100) səhifənin ölçüsünü məhdudlaşdırır.
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-cü hissə. exclude_unset=True yalnız müştərinin həqiqətən göndərdiyi sahələri verir; onsuz göndərilməyən title None olardı və baza NOT NULL xətası verərdi. TaskDep və SessionDep eyni sorğuda eyni sessiyanı alır (asılılıq keşi), ona görə tapılmış obyekti dəyişib commit etmək olur.
SorğuUğurXəta
POST /tasks201 Created422 — gövdə sxemə uyğun deyil
GET /tasks?skip=0&limit=20200 OK422 — limit > 100
GET /tasks/{task_id}200 OK404 — tapşırıq yoxdur
PATCH /tasks/{task_id}200 OK404 / 422
DELETE /tasks/{task_id}204 — gövdəsiz404
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'])

Gözlənilən nəticə

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
Boş bazada icra olunub. PATCH yalnız done-u dəyişib, başlıq qalıb. 204 cavabının gövdəsi boşdur. Pydantic xətaları detail siyahısında yeri (loc) və səbəbi (msg) göstərir.

Routerlər, async və arxa fon işləri

Endpoint-lər çoxaldıqca onları mövzulara görə fayllara bölürlər: APIRouter(prefix='/tasks', tags=['tasks']) Flask-ın blueprintinə bənzəyir və app.include_router(router) ilə qoşulur; tags /docs səhifəsində qrupları yaradır. BackgroundTasks cavab göndəriləndən sonra kiçik işi (e-poçt, jurnal yazısı) icra edir — müştəri onu gözləmir. Uzun və vacib işlər üçün isə ayrıca növbə (Celery, RQ) istifadə olunur.

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']))

Gözlənilən nəticə

{'status': 'queued'} ['report 7 sent']
['/reports/{report_id}/send']
202 Accepted «qəbul olundu, sonra icra olunacaq» deməkdir. TestClient arxa fon işini cavabdan sonra, post() qayıtmazdan əvvəl icra edir, ona görə jurnal artıq doludur.

TestClient və müvəqqəti baza ilə testlər

Asılılıqların ən böyük üstünlüyü testlərdə görünür: app.dependency_overrides[get_db] = override_get_db real bazanı testlər üçün başqası ilə əvəz edir, kodun özünə toxunmadan. Yaddaşdakı SQLite (sqlite://) hər test qaçışında təmiz başlayır. Amma yaddaş bazası qoşulmaya bağlıdır, ona görə StaticPool istifadə edirik: bütün sessiyalar bir qoşulmanı paylaşır və eyni cədvəlləri görür. Testləri «pytest ilə testləşdirmə» dərsindəki kimi assert ilə yazırıq.

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-ci hissə: müvəqqəti baza və asılılığın əvəzlənməsi.
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-ci hissə: üç test. İkinci test PATCH-in göndərilməyən sahəyə toxunmadığını yoxlayır — exclude_unset səhvini məhz belə test tutar.
Terminal
python -m pytest -q test_main.py

Gözlənilən nəticə

...                                                                      [100%]
3 passed in 1.20s
Hər nöqtə keçən bir testdir; vaxt hər dəfə fərqlidir. Starlette-in yeni versiyaları test müştərisinin HTTP kitabxanası haqqında xəbərdarlıq da çap edə bilər — testlərin nəticəsinə təsir etmir.

Tapşırıq

Mini Depends yaz: solve(func) funksiyanın parametrlərinə baxsın (inspect.signature), standart dəyəri Depends(dep) olan hər parametr üçün əvvəlcə dep-i (rekursiv) həll etsin və nəticəni ötürsün. FastAPI kimi, bir «sorğu» daxilində hər asılılıq yalnız bir dəfə çağırılmalıdır (cache).

Tapşırıq · 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)
Gözlənilən nəticə
repo with session(sqlite://); session(sqlite://)
['settings', 'db', 'repo']

Tapşırıq

yield-li asılılığın necə işlədiyini təkrarla: run(endpoint, *args) get_db() generatorunu başlatsın, next() ilə «sessiyanı» alsın, endpoint-i çağırıb (200, nəticə) qaytarsın; HTTPError olsa (status, {'detail': ...}) qaytarsın. Hər halda sonda generatoru bağlasın ki, finally işləsin.

Tapşırıq · 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)
Gözlənilən nəticə
(200, 'Learn Depends')
(404, {'detail': 'Task not found'})
['open', 'close', 'open', 'close']

Yadda saxla

  • Depends(f) FastAPI-yə f-i hər sorğuda çağırıb nəticəni ötürməyi deyir; asılılıqların da asılılıqları ola bilər, bir sorğuda hər biri bir dəfə həll olunur.
  • yield + finally ilə get_db sessiyanı sorğudan əvvəl açır və sonra mütləq bağlayır; Annotated ləqəbləri (SessionDep) təkrarı azaldır.
  • Model ≠ sxem: TaskCreate / TaskUpdate / TaskRead; response_model cavabı süzür, PATCH-də exclude_unset=True.
  • 201 yaradılanda, 204 silinəndə, 404 HTTPException ilə, 422 isə yoxlama xətasında; routerlər endpoint-ləri fayllara bölür.
  • Testdə app.dependency_overrides[get_db] + sqlite:// + StaticPool; bloklayan kod def-də, async def-də yalnız await.
Dərsdə səhv və ya qeyri-dəqiqlik gördün?

Özünü yoxla

12 sual. Hər düzgün cavab XP qazandırır.

Sual 1 / 12

Sual 1 / 12. Endpoint parametrində db: Annotated[Session, Depends(get_db)] nə deməkdir?