FastAPI: bağımlılıklar ve veritabanı

`Depends` ve bağımlılık ağaçları, `yield`'li bir bağımlılıkla istek başına bir SQLAlchemy oturumu, Pydantic şemalarıyla CRUD, durum kodları ve `HTTPException`, router'lar, async ve arka plan görevleri, `TestClient` ve geçici veritabanıyla testler.

  • İleri
  • 25 dk
  • 12 soru
  • Ders 46 / 66

Bu derste öğreneceklerin

  • Depends ile bağımlılıklar ve bağımlılık ağaçları kurmak, istek içi önbelleklerini açıklamak
  • yield'li bir bağımlılıkla istek başına bir SQLAlchemy oturumu açıp kapatmak
  • Pydantic şemaları, response_model, doğru durum kodları ve HTTPException ile CRUD uç noktaları yazmak
  • API'yi TestClient, dependency_overrides ve geçici bir veritabanıyla test etmek

«FastAPI ile web servisi» dersinde görevler bellekteki bir sözlükte duruyordu: sunucu yeniden başlayınca hepsi kayboluyordu. Gerçek bir API verisini veritabanında tutar ve her istekte aynı işleri yapar: veritabanına bağlanır, kullanıcıyı denetler, sayfalama parametrelerini okur. Bu tekrarlanan parçaları her fonksiyona kopyalamak yerine FastAPI bağımlılıkları (dependency injection) kullanır. Bu derste Depends'i, istek başına bir SQLAlchemy oturumunu, Pydantic şemalarıyla CRUD'u, hataları ve geçici veritabanlı testleri öğreneceğiz.

Bağımlılıklar: Depends

Bağımlılık (dependency)Tanım

Bir uç noktanın çalışması için gereken ve FastAPI'nin kendisinin hazırlayıp verdiği değer. Bir parametrede Depends(fonksiyon) yazıldığında FastAPI her istekte o fonksiyonu çağırır ve sonucunu parametreye koyar. Bağımlılığın kendi parametreleri (sorgu parametreleri, başlıklar ve başka bağımlılıklar) olabilir; böylece bir bağımlılık ağacı oluşur.

Aşağıdaki örnekte lessons uç noktası iki şeye bağlıdır: sayfalama parametrelerine ve o anki kullanıcıya. current_user da kendi sırasında get_token'a bağlıdır; o da X-Token başlığını okur. Belirteç yanlışsa HTTPException(401), isteği uç noktaya ulaşmadan durdurur. Annotated[tür, Depends(...)] yazımı türü ve bağımlılığı bir arada tutar; yeniden kullanmak için bir takma ada (örneğin SessionDep) dönüştürülebilir.

  1. Rota bulunur

    FastAPI yolu ve yöntemi bir uç noktaya eşler.

  2. Bağımlılıklar çözülür

    Ağaç yapraklardan yukarı doğru çözülür, her bağımlılık bir kez; parametreler ve gövde doğrulanır. Bir bağımlılığın HTTPException'ı ya da bir doğrulama hatası (422) isteği burada durdurur.

  3. Uç nokta çalışır

    Fonksiyon hazır değerleri argüman olarak alır.

  4. Yanıt ve temizlik

    Sonuç response_model ile süzülür, JSON'a çevrilir ve gönderilir; ardından yield'li bağımlılıkların finally kısmı çalışır.

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

Beklenen çıktı

401 {'detail': 'Invalid token'}
200 {'user': 'Aysel', 'skip': 0, 'limit': 5}
FastAPI tarayıcıda çalışmaz; kodu pip install "fastapi[standard]" sqlalchemy komutundan sonra kendi bilgisayarında çalıştır. Header(), x_token parametre adını X-Token başlığına eşler. limit=5 sorgu parametresi bağımlılığa (pagination) ulaştı.

Okumaya devam etmek için ücretsiz kaydol

Dersin geri kalan bölümleri, test ve notlar Educora hesabıyla açılır. Kayıt bir dakika sürer; ilerlemen tüm cihazlarında saklanır.

İstek başına bir oturum

Bir bağımlılık return yerine yield kullanabilir. O zaman yield'den önceki kısım uç noktadan önce, finally bloğundaki kısım ise yanıt hazır olduktan sonra çalışır; hata olsa bile. Bu, «Bağlam yöneticileri ve with deyimi» dersindeki with ile aynı fikirdir ve bir veritabanı bağlantısı için idealdir. Bir de şu: aynı istekte bir bağımlılık birkaç yerde kullanılırsa FastAPI onu bir kez çağırır ve sonucu hatırlar.

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

Beklenen çıktı

open resource
endpoint got {'id': 1} call 1
close resource
{'ok': True}
get_resource hem uç noktada hem de counter içinde gerekiyor ama “open resource” bir kez yazdırıldı; istek içi önbellek. “close resource” uç noktadan sonra geliyor.

Şimdi gerçek veri katmanı. database.py, motoru («SQLAlchemy: ORM ile veritabanı» dersine bak), SessionLocal oturum fabrikasını ve get_db bağımlılığını tutar: her istek kendi oturumunu alır ve sonunda kapatır. check_same_thread=False gereklidir, çünkü FastAPI sıradan def uç noktalarını iş parçacıklarında (thread) çalıştırır; SQLite ise varsayılan olarak bir bağlantının yalnızca onu oluşturan iş parçacığında kullanılmasına izin 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 şemalarıyla CRUD

SQLAlchemy modeli veritabanındaki tabloyu, Pydantic şeması ise API'nin “sözleşmesini” tanımlar («Pydantic: veri doğrulama» dersine bak). Onları ayırmak önemlidir: TaskCreate istemcinin gönderebileceği alanlardır (id yok, onu veritabanı verir), TaskUpdate içindeki tüm alanlar isteğe bağlıdır (PATCH yalnızca değişeni gönderir), TaskRead ise yanıtta neyin görüneceğini belirler. from_attributes=True, şemanın bir ORM nesnesinin özniteliklerinden kurulmasını sağlar.

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ş ve çıkış şemaları.
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. bölüm. get_task_or_404 kendisi de bir bağımlılıktır: yol parametresi task_id'yi ve oturumu alır, görev yoksa 404 fırlatır. Böylece “bul ya da 404” mantığı üç uç noktada tekrarlanmaz.
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. bölüm: oluşturma, liste ve tek görev. response_model=TaskRead, ORM nesnesini şemaya çevirir ve şemada olmayan alanları (örneğin ileride eklenecek bir owner_password_hash) yanıtın dışında tutar. Query(le=100) sayfa boyutunu sınırlar.
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. bölüm. exclude_unset=True yalnızca istemcinin gerçekten gönderdiği alanları verir; o olmadan gönderilmeyen title None olur ve veritabanı bir NOT NULL hatası verirdi. TaskDep ve SessionDep aynı istekte aynı oturumu alır (bağımlılık önbelleği); bu yüzden bulunan nesne değiştirilip commit edilebilir.
İstekBaşarıHata
POST /tasks201 Created422 — gövde şemaya uymuyor
GET /tasks?skip=0&limit=20200 OK422 — limit > 100
GET /tasks/{task_id}200 OK404 — böyle bir görev yok
PATCH /tasks/{task_id}200 OK404 / 422
DELETE /tasks/{task_id}204 — gövdesiz404
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'])

Beklenen çıktı

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ş bir veritabanında çalıştırıldı. PATCH yalnızca done'u değiştirdi, başlık kaldı. 204 yanıtının gövdesi boştur. Pydantic hataları detail listesinde yeri (loc) ve nedeni (msg) gösterir.

Router'lar, async ve arka plan görevleri

Uç noktalar çoğaldıkça konulara göre dosyalara bölünür: APIRouter(prefix='/tasks', tags=['tasks']) Flask'taki blueprint'e benzer ve app.include_router(router) ile bağlanır; tags, /docs sayfasında gruplar oluşturur. BackgroundTasks, yanıt gönderildikten sonra küçük bir işi (e-posta, günlük kaydı) çalıştırır; istemci onu beklemez. Uzun ya da önemli işler ayrı bir kuyruğa (Celery, RQ) konur.

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

Beklenen çıktı

{'status': 'queued'} ['report 7 sent']
['/reports/{report_id}/send']
202 Accepted “kabul edildi, sonra yapılacak” demektir. TestClient arka plan görevini yanıttan sonra ama post() dönmeden önce çalıştırır; bu yüzden günlük zaten dolu.

TestClient ve geçici veritabanıyla testler

Bağımlılıkların en büyük faydası testlerde görünür: app.dependency_overrides[get_db] = override_get_db, koda dokunmadan gerçek veritabanını testler süresince başka biriyle değiştirir. Bellekteki SQLite (sqlite://) her test çalıştırmasında temiz başlar. Ama bellek veritabanı bir bağlantıya bağlıdır; bu yüzden StaticPool kullanırız: tüm oturumlar tek bir bağlantıyı paylaşır ve aynı tabloları görür. Testleri «pytest ile test yazma» dersindeki gibi assert ile yazarız.

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. bölüm: geçici veritabanı ve bağımlılığın değiştirilmesi.
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. bölüm: üç test. İkinci test, PATCH'in gönderilmeyen bir alana dokunmadığını denetler; unutulmuş bir exclude_unset hatasını tam da böyle bir test yakalar.
Terminal
python -m pytest -q test_main.py

Beklenen çıktı

...                                                                      [100%]
3 passed in 1.20s
Her nokta geçen bir testtir; süre her çalıştırmada farklıdır. Starlette'in yeni sürümleri test istemcisinin HTTP kütüphanesi hakkında bir uyarı da yazdırabilir; sonucu etkilemez.

Alıştırma

Küçük bir Depends yaz: solve(func) fonksiyonun parametrelerine (inspect.signature) bakmalı ve varsayılan değeri Depends(dep) olan her parametre için önce dep'i (özyinelemeli olarak) çözüp sonucu vermeli. FastAPI'deki gibi bir “istek” içinde her bağımlılık yalnızca bir kez çağrılmalı (cache).

Alıştırma · 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)
Beklenen çıktı
repo with session(sqlite://); session(sqlite://)
['settings', 'db', 'repo']

Alıştırma

yield'li bir bağımlılığın nasıl çalıştığını tekrarla: run(endpoint, *args) get_db() üretecini başlatmalı, “oturumu” next() ile almalı, uç noktayı çağırıp (200, sonuç) döndürmeli; HTTPError olursa (status, {'detail': ...}) döndürmeli. Her durumda finally çalışsın diye sonunda üreteci kapatmalı.

Alıştırma · 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)
Beklenen çıktı
(200, 'Learn Depends')
(404, {'detail': 'Task not found'})
['open', 'close', 'open', 'close']

Unutma

  • Depends(f), FastAPI'ye f'yi her istekte çağırıp sonucu vermesini söyler; bağımlılıkların da bağımlılıkları olabilir ve her biri bir istekte bir kez çözülür.
  • yield + finally ile get_db oturumu istekten önce açar ve sonra mutlaka kapatır; Annotated takma adları (SessionDep) tekrarı azaltır.
  • Model ≠ şema: TaskCreate / TaskUpdate / TaskRead; response_model yanıtı süzer, PATCH'te exclude_unset=True kullanılır.
  • Oluşturmada 201, silmede 204, HTTPException ile 404, doğrulama hatasında 422; router'lar uç noktaları dosyalara böler.
  • Testlerde: app.dependency_overrides[get_db] + sqlite:// + StaticPool; engelleyen kod def içinde, async def içinde yalnızca await.
Bu derste bir hata ya da yanlışlık mı gördün?

Kendini test et

12 soru. Her doğru cevap XP kazandırır.

Soru 1 / 12

Soru 1 / 12. Bir uç noktanın parametrelerinde db: Annotated[Session, Depends(get_db)] ne demektir?