0 dní v řadě · 0 bodů

Profesionální vývoj · 40 min

API ve FastAPI

Z obyčejných funkcí s typy uděláš webové API s validací a dokumentací a pochopíš, co framework dělá za tebe.

Hloubka
Úkoly
Lidsky řečeno

Kuchař umí vařit, ale nechce běhat ke stolům. Číšník vezme objednávku, ověří, že to jídlo je na lístku, předá ji do kuchyně a přinese talíř. Když si host objedná něco, co neexistuje, kuchař se o tom vůbec nedozví. FastAPI je ten číšník. Tvoje funkce jsou kuchaři a jídelní lístek si číšník napíše sám podle nich.

Proč vůbec framework

V lekci HTTP a návrh REST API jsi viděl, z čeho se skládá požadavek: metoda, cesta, parametry, hlavičky a tělo. Každý koncový bod (anglicky endpoint, jedna adresa s jednou metodou) musí udělat pořád totéž: rozebrat adresu, převést text na čísla, zkontrolovat data, poslat srozumitelnou chybu a výsledek převést na JSON.

FastAPI je knihovna, která tuhle rutinu odvodí z typů, které u funkce stejně píšeš. Instalace do virtuálního prostředí:

bash
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install "fastapi[standard]"

Celá první aplikace:

main.py
from fastapi import FastAPI

app = FastAPI(title="Úkolníček")


@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}


@app.get("/tasks/{task_id}")
def read_task(task_id: int, detail: bool = False) -> dict[str, object]:
    return {"id": task_id, "detail": detail}

Spustíš ji vývojovým serverem, který se po každé změně souboru sám restartuje:

bash
fastapi dev main.py

Na http://127.0.0.1:8000/docs teď najdeš interaktivní dokumentaci, kde jde každý endpoint rovnou vyzkoušet. Nenapsal jsi pro ni ani řádek. A takhle se server chová:

PožadavekOdpověď
GET /tasks/7200 a {"id": 7, "detail": false}
GET /tasks/7?detail=true200 a {"id": 7, "detail": true}
GET /tasks/sedm422, protože sedm není celé číslo
GET /neexistuje404

Pravidlo, odkud se hodnota vezme, je jednoduché:

  • Jméno je v cestě ve složených závorkách: parametr cesty.
  • Jednoduchý typ, který v cestě není: query parametr za otazníkem. S výchozí hodnotou je nepovinný.
  • Třída odvozená od BaseModel: tělo požadavku v JSONu.

Co se děje uvnitř

Kouzlo se líp chápe, když si ho napíšeš sám. Následujících pár desítek řádků je zmenšenina toho, co FastAPI dělá: dekorátor si funkci zapamatuje, inspect.signature přečte její parametry a typy a podle nich se text z adresy převede.

import inspect
import json
from urllib.parse import parse_qsl, urlsplit


def convert(raw, target):
    if target is bool:
        word = raw.lower()
        if word in {"1", "true", "yes", "on"}:
            return True
        if word in {"0", "false", "no", "off"}:
            return False
        raise ValueError(raw)
    return target(raw)


def match_path(pattern, path):
    want = pattern.strip("/").split("/")
    got = path.strip("/").split("/")
    if len(want) != len(got):
        return None
    params = {}
    for expected, actual in zip(want, got):
        if expected.startswith("{"):
            params[expected[1:-1]] = actual
        elif expected != actual:
            return None
    return params


class MiniAPI:
    def __init__(self):
        self.routes = []

    def get(self, pattern):
        def register(func):
            self.routes.append((pattern, func))
            return func
        return register

    def call(self, func, raw_values):
        kwargs, errors = {}, []
        for name, param in inspect.signature(func).parameters.items():
            if name in raw_values:
                try:
                    kwargs[name] = convert(raw_values[name], param.annotation)
                except ValueError:
                    errors.append({"loc": name, "msg": "špatný typ"})
            elif param.default is inspect.Parameter.empty:
                errors.append({"loc": name, "msg": "chybí"})
        if errors:
            return 422, {"detail": errors}
        return 200, func(**kwargs)

    def handle(self, url):
        parts = urlsplit(url)
        for pattern, func in self.routes:
            params = match_path(pattern, parts.path)
            if params is not None:
                return self.call(func, dict(parse_qsl(parts.query)) | params)
        return 404, {"detail": "Not Found"}


app = MiniAPI()


@app.get("/tasks/{task_id}")
def read_task(task_id: int, detail: bool = False):
    return {"id": task_id, "detail": detail}


for url in ["/tasks/7", "/tasks/7?detail=true", "/tasks/sedm", "/nic"]:
    status, body = app.handle(url)
    print(status, json.dumps(body, ensure_ascii=False))
Výstup
200 {"id": 7, "detail": false}
200 {"id": 7, "detail": true}
422 {"detail": [{"loc": "task_id", "msg": "špatný typ"}]}
404 {"detail": "Not Found"}

Všimni si dvou věcí. Funkce read_task nedostane špatná data, protože se k ní vůbec nedostanou. A bool potřebuje zvláštní zacházení, protože bool("false") je v Pythonu True: každý neprázdný text je pravdivý.

Úkol

Napiš párování cest

Doplň funkci match_path(pattern, path). Vrátí slovník parametrů, když cesta odpovídá vzoru, jinak None. Vzor /users/{uid}/tasks/{tid} a cesta /users/5/tasks/9 dají {"uid": "5", "tid": "9"}. Vzor bez parametrů, který sedí, dá prázdný slovník. Lomítko na začátku a na konci nehraje roli.

def match_path(pattern, path):
    # doplň
    return None
Výstup
Kvíz

Klient pošle GET /tasks/abc a funkce má task_id: int. Co se stane?

Pod kapotou · ASGI: co je pod FastAPI

FastAPI stojí na Starlette (směrování, požadavky, odpovědi) a Pydanticu (validace, jehož jádro je v Rustu). Server, typicky Uvicorn, s aplikací mluví protokolem ASGI: aplikace je asynchronní funkce se třemi argumenty. Žádná magie, jde to zavolat ručně, a přesně takhle se dají psát middlewary bez závislosti na frameworku.

import asyncio
import json


async def app(scope, receive, send):
    body = json.dumps({"path": scope["path"]}).encode()
    await send({
        "type": "http.response.start",
        "status": 200,
        "headers": [(b"content-type", b"application/json")],
    })
    await send({"type": "http.response.body", "body": body})


async def fake_server():
    async def receive():
        return {"type": "http.request", "body": b"", "more_body": False}

    async def send(message):
        print(message["type"], message.get("status", message.get("body")))

    await app({"type": "http", "method": "GET", "path": "/ahoj"}, receive, send)


asyncio.run(fake_server())
Výstup
http.response.start 200
http.response.body b'{"path": "/ahoj"}'

Důsledek pro návrh: analýza signatur a stavba validátorů proběhne při registraci tras, tedy při importu. Za běhu se už jen vyhodnocují hotové validátory. Pomalý start velké aplikace proto často neznamená pomalé požadavky. A pozor na meze: FastAPI ani Uvicorn samy neomezují velikost těla požadavku, to je práce reverzní proxy nebo vlastního ASGI middlewaru.

Data v těle: Pydantic

Query parametry stačí na filtrování. Když klient něco vytváří, pošle JSON v těle. Jeho tvar popíšeš třídou odvozenou od BaseModel z knihovny Pydantic. Vypadá jako dataclass, ale při vytvoření data opravdu kontroluje.

from pydantic import BaseModel, Field, ValidationError


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    priority: int = Field(default=3, ge=1, le=5)
    done: bool = False


task = TaskCreate.model_validate({"title": "Koupit mléko", "priority": "2"})
print(task)
print(task.model_dump())

try:
    TaskCreate.model_validate({"title": "", "priority": 9})
except ValidationError as error:
    for item in error.errors():
        print(item["loc"], item["type"])
Výstup
title='Koupit mléko' priority=2 done=False
{'title': 'Koupit mléko', 'priority': 2, 'done': False}
('title',) string_too_short
('priority',) less_than_equal

ge znamená „větší nebo rovno“, le „menší nebo rovno“. Text "2" se převedl na číslo, protože Pydantic ve výchozím režimu rozumné převody dělá. Chyby nesbírá po jedné: nahlásí všechny najednou, takže klient opraví formulář na jeden pokus.

Úkol

Model registrace

Doplň model Registrace:

  • username: text o délce 3 až 20 znaků, jen malá písmena bez diakritiky, číslice a podtržítko,
  • age: celé číslo, nejméně 18,
  • newsletter: logická hodnota, výchozí False,
  • neznámá pole se mají odmítnout. Nastav to přes model_config = ConfigDict(extra="forbid").
from pydantic import BaseModel, ConfigDict, Field


class Registrace(BaseModel):
    username: str
    age: int
Výstup

Tady je úplné API nad pamětí. Stavový kód 201 znamená „vytvořeno“, 204 „hotovo a nic nevracím“. Návratový typ není jen ozdoba: FastAPI podle něj odpověď zkontroluje, odfiltruje pole navíc a popíše ji v dokumentaci.

main.py
from itertools import count
from typing import Annotated

from fastapi import FastAPI, HTTPException, Query, status
from pydantic import BaseModel, Field

app = FastAPI(title="Úkolníček")


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    priority: int = Field(default=3, ge=1, le=5)


class TaskPatch(BaseModel):
    title: str | None = Field(default=None, min_length=1, max_length=200)
    priority: int | None = Field(default=None, ge=1, le=5)


class TaskOut(TaskCreate):
    id: int


tasks: dict[int, TaskOut] = {}
ids = count(1)


def find_task(task_id: int) -> TaskOut:
    task = tasks.get(task_id)
    if task is None:
        raise HTTPException(status.HTTP_404_NOT_FOUND, "Úkol neexistuje")
    return task


@app.post("/tasks", status_code=status.HTTP_201_CREATED)
def create_task(payload: TaskCreate) -> TaskOut:
    task = TaskOut(id=next(ids), **payload.model_dump())
    tasks[task.id] = task
    return task


@app.get("/tasks")
def list_tasks(
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
    offset: Annotated[int, Query(ge=0)] = 0,
) -> list[TaskOut]:
    return list(tasks.values())[offset : offset + limit]


@app.get("/tasks/{task_id}")
def read_task(task_id: int) -> TaskOut:
    return find_task(task_id)


@app.patch("/tasks/{task_id}")
def update_task(task_id: int, payload: TaskPatch) -> TaskOut:
    changes = payload.model_dump(exclude_unset=True)
    task = find_task(task_id).model_copy(update=changes)
    tasks[task_id] = task
    return task


@app.delete("/tasks/{task_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_task(task_id: int) -> None:
    find_task(task_id)
    del tasks[task_id]

exclude_unset=True vrátí jen pole, která klient opravdu poslal. Díky tomu PATCH pozná rozdíl mezi „titulek neměň“ a „titulek jsem poslal“.

Pod kapotou · kudy uniká, co nemělo

Filtrování podle návratového typu platí, jen když vracíš data. Když vrátíš přímo JSONResponse, validace odpovědi se přeskočí a pole navíc odejdou klientovi. Pokud funkce vrací bohatší objekt, než chceš ukázat, použij response_model=UserOut: má přednost před anotací a mypy zůstane spokojený.

python
@app.get("/me", response_model=UserOut)
def me() -> UserInDb:
    return load_current_user()

U model_copy(update=...) si dej pozor, že hodnoty se nevalidují. Ukázka výše na to má slabé místo: klient může poslat "title": null, typ str | None to pustí, exclude_unset pole nechá a do úkolu se zapíše None, přestože TaskOut slibuje text. Hotová instance se při výstupu ve výchozím nastavení Pydanticu znovu nevaliduje (revalidate_instances="never"), takže taková hodnota může dojít až ke klientovi. V produkci to řeš validátorem, nebo pole s None z changes vyřaď. U modelů pro PATCH mají „chybí“ a „null“ opravdu dva různé významy.

Databáze a závislosti

Skoro každý endpoint potřebuje totéž: připojení k databázi, přihlášeného uživatele, nastavení. Místo opakování řekneš, co funkce potřebuje, a framework jí to dodá. Říká se tomu vkládání závislostí (dependency injection). Znovu zmenšenina, tentokrát jde o mechanismus Depends:

import inspect


class Depends:
    def __init__(self, provider):
        self.provider = provider


def call_with_deps(func, overrides, cache, cleanups):
    kwargs = {}
    for name, param in inspect.signature(func).parameters.items():
        if isinstance(param.default, Depends):
            wanted = param.default.provider
            provider = overrides.get(wanted, wanted)
            if provider not in cache:
                cache[provider] = call_with_deps(provider, overrides, cache, cleanups)
            kwargs[name] = cache[provider]
    result = func(**kwargs)
    if inspect.isgenerator(result):
        cleanups.append(result)
        return next(result)
    return result


def run_request(func, overrides=None):
    cleanups = []
    try:
        return call_with_deps(func, overrides or {}, {}, cleanups)
    finally:
        for generator in reversed(cleanups):
            next(generator, None)


def get_db():
    print("otevírám databázi")
    yield "spojení"
    print("zavírám databázi")


def get_user(db=Depends(get_db)):
    print("hledám uživatele přes", db)
    return "Eva"


def endpoint(user=Depends(get_user), db=Depends(get_db)):
    print("obsluhuji", user, "přes", db)
    return {"user": user}


print(run_request(endpoint))
print("--- v testu podstrčíme uživatele")
print(run_request(endpoint, {get_user: lambda: "Testovací Tom"}))
Výstup
otevírám databázi
hledám uživatele přes spojení
obsluhuji Eva přes spojení
zavírám databázi
{'user': 'Eva'}
--- v testu podstrčíme uživatele
otevírám databázi
obsluhuji Testovací Tom přes spojení
zavírám databázi
{'user': 'Testovací Tom'}

Databáze se otevřela jednou, přestože ji chtěly dvě funkce: v rámci jednoho požadavku se výsledek závislosti pamatuje. Kód za yield je úklid a běží i při chybě. A slovník overrides je přesně to, co ti ve FastAPI umožní v testech vyměnit skutečnou závislost za falešnou.

Ve skutečném FastAPI s sqlite3 to vypadá takhle. Alias přes Annotated ušetří opakování:

main.py
import sqlite3
from collections.abc import AsyncIterator, Iterator
from contextlib import asynccontextmanager
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, status
from pydantic import BaseModel, Field

DB_PATH = "tasks.db"
SCHEMA = """
CREATE TABLE IF NOT EXISTS tasks (
    id INTEGER PRIMARY KEY,
    title TEXT NOT NULL,
    priority INTEGER NOT NULL
);
"""


@asynccontextmanager
async def lifespan(app: FastAPI) -> AsyncIterator[None]:
    conn = sqlite3.connect(DB_PATH)      # runs once at startup
    conn.executescript(SCHEMA)
    conn.close()
    yield                                # the app serves requests here


app = FastAPI(title="Úkolníček", lifespan=lifespan)


def get_db() -> Iterator[sqlite3.Connection]:
    # FastAPI may run this and the endpoint in different threads.
    conn = sqlite3.connect(DB_PATH, check_same_thread=False)
    conn.row_factory = sqlite3.Row
    try:
        yield conn
        conn.commit()
    except Exception:
        conn.rollback()
        raise
    finally:
        conn.close()


Db = Annotated[sqlite3.Connection, Depends(get_db)]


class TaskCreate(BaseModel):
    title: str = Field(min_length=1, max_length=200)
    priority: int = Field(default=3, ge=1, le=5)


class TaskOut(TaskCreate):
    id: int


@app.post("/tasks", status_code=status.HTTP_201_CREATED)
def create_task(payload: TaskCreate, db: Db) -> TaskOut:
    cursor = db.execute(
        "INSERT INTO tasks (title, priority) VALUES (?, ?)",
        (payload.title, payload.priority),
    )
    return TaskOut(id=cursor.lastrowid, **payload.model_dump())


@app.get("/tasks/{task_id}")
def read_task(task_id: int, db: Db) -> TaskOut:
    row = db.execute(
        "SELECT id, title, priority FROM tasks WHERE id = ?", (task_id,)
    ).fetchone()
    if row is None:
        raise HTTPException(status.HTTP_404_NOT_FOUND, "Úkol neexistuje")
    return TaskOut(**dict(row))

lifespan je kód, který běží jednou při startu (před yield) a jednou při vypnutí (za ním). Hodí se pro přípravu schématu, načtení modelu nebo vytvoření sdíleného klienta. Otazníky v SQL znáš z lekce SQL a sqlite3: hodnoty se nikdy nelepí do textu dotazu.

Pod kapotou · závislosti s yield v praxi

Vlákna. Synchronní závislost i synchronní endpoint jdou do poolu vláken, každý zvlášť, klidně do jiného vlákna. Výchozí check_same_thread=True by proto náhodně házelo ProgrammingError. Vypnutí je tady bezpečné, protože spojení patří jednomu požadavku a nikdo ho nepoužívá souběžně.

Čas úklidu. Kdy přesně běží kód za yield vzhledem k odeslání odpovědi, se mezi verzemi FastAPI měnilo (změny přinesly verze 0.106 a 0.118). U běžné JSON odpovědi to nepoznáš. U StreamingResponse, který čte z databáze, na tom závisí, jestli je spojení ještě otevřené. Ověř si chování ve své verzi a v release notes.

Commit a odpověď. Když conn.commit() běží až po vytvoření odpovědi a selže, klient už mohl dostat 201 na zápis, který neexistuje. Kde na tom záleží, commituj explicitně uvnitř endpointu nebo service vrstvy, než odpověď vrátíš.

Cache. Výsledek se pamatuje v rámci požadavku podle funkce. Depends(get_x, use_cache=False) to vypne. Parametrizovaná závislost jako třída s __call__ se klíčuje podle instance, takže dvě různé instance se volají zvlášť.

Chyby: doména nemá znát HTTP

HTTPException je pohodlná, ale patří jen do vrstvy API. Funkce, která počítá nebo ukládá, by neměla vědět, že existuje stav 404. Jinak ji nepůjde použít z příkazové řádky ani z fronty úloh. Doména vyhodí vlastní výjimku a jedno místo ji přeloží:

python
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()


class TaskNotFound(Exception):
    pass


@app.exception_handler(TaskNotFound)
def task_not_found(request: Request, error: TaskNotFound) -> JSONResponse:
    return JSONResponse(status_code=404, content={"detail": "Úkol neexistuje"})
Úkol

Překlad výjimek na odpovědi

Napiš to_http(func, *args). Zavolá func(*args) a vrátí dvojici (stav, tělo):

  • bez chyby (200, výsledek),
  • TaskNotFound dá (404, {"detail": "Úkol neexistuje"}),
  • TaskConflict dá (409, {"detail": "Úkol už existuje"}),
  • jakákoli jiná výjimka dá (500, {"detail": "Interní chyba"}). Text původní výjimky do odpovědi nepatří, mohou v něm být citlivé údaje.
class TaskNotFound(Exception):
    pass


class TaskConflict(Exception):
    pass


tasks = {1: "Koupit mléko"}


def get_task(task_id):
    if task_id not in tasks:
        raise TaskNotFound(task_id)
    return {"id": task_id, "title": tasks[task_id]}


def add_task(task_id, title):
    if task_id in tasks:
        raise TaskConflict(task_id)
    tasks[task_id] = title
    return {"id": task_id, "title": title}


def to_http(func, *args):
    return 200, func(*args)
Výstup
Kvíz

Jaký stav FastAPI vrátí, když tělo požadavku neodpovídá modelu Pydantic?

def, nebo async def

FastAPI přijme obojí a rozdíl je podstatný.

  • def se spustí ve vlákně z připraveného poolu. Může v klidu čekat na databázi nebo soubor.
  • async def běží přímo ve smyčce událostí, kterou sdílí všechny požadavky. Tam se smí čekat jen přes await.

Co se stane, když v async def zavoláš něco blokujícího, ukáže tenhle pokus. time.sleep nepustí k slovu nikoho dalšího, asyncio.sleep ano.

import asyncio
import time


async def blocking(log):
    log.append("blokující začátek")
    time.sleep(0.05)
    log.append("blokující konec")


async def polite(log):
    log.append("slušný začátek")
    await asyncio.sleep(0.05)
    log.append("slušný konec")


async def other_request(log):
    log.append("jiný požadavek obsloužen")


async def main():
    for handler in (blocking, polite):
        log = []
        await asyncio.gather(handler(log), other_request(log))
        print(log)


asyncio.run(main())
Výstup
['blokující začátek', 'blokující konec', 'jiný požadavek obsloužen']
['slušný začátek', 'jiný požadavek obsloužen', 'slušný konec']
Lidsky řečeno

Smyčka událostí je jeden číšník na celou restauraci. Zvládne desítky stolů, protože u žádného nestojí a nečeká. Když si ale jeden host řekne, ať číšník počká, než dočte jídelní lístek, a ten opravdu čeká, všichni ostatní hladoví. await znamená „zavolej mě, až bude host hotový, a běž zatím jinam“.

Praktické pravidlo: používáš-li sqlite3, requests nebo jiné blokující knihovny, piš obyčejné def. async def použij, když všechno, na co čekáš, má asynchronní verzi, například httpx.AsyncClient.

Pod kapotou · pool vláken a výpočty

Synchronní handlery jdou přes anyio.to_thread s výchozím limitem 40 souběžných vláken. Když jsou všechna obsazená pomalým I/O, další požadavky čekají, i když CPU nic nedělá. Latence pak skočí bez jediné chyby v logu, proto měř čekání, ne jen dobu handleru.

Výpočetně náročná práce nepomůže ani ve vlákně, protože ve standardním buildu CPythonu 3.12 drží GIL. Patří do procesu (ProcessPoolExecutor) nebo do fronty s workerem. BackgroundTasks z FastAPI běží v tom samém procesu po odeslání odpovědi: při pádu nebo restartu se ztratí, takže na nic, co se musí stát, nejsou vhodné.

Z async def zavoláš blokující kód přes await run_in_threadpool(func, arg) ze starlette.concurrency, případně standardním asyncio.to_thread.

Kvíz

Endpoint volá requests.get(...) a nic asynchronního nepoužívá. Jak ho napsat?

Testy bez serveru

TestClient volá aplikaci přímo, bez sítě a bez spuštěného Uvicornu. Díky dependency_overrides dostane test vlastní databázi v paměti. Je potřeba balík httpx, který fastapi[standard] přináší.

test_main.py
import sqlite3

import pytest
from fastapi.testclient import TestClient

from main import SCHEMA, app, get_db


@pytest.fixture
def client():
    conn = sqlite3.connect(":memory:", check_same_thread=False)
    conn.row_factory = sqlite3.Row
    conn.executescript(SCHEMA)

    def override_db():
        yield conn

    app.dependency_overrides[get_db] = override_db
    yield TestClient(app)
    app.dependency_overrides.clear()
    conn.close()


def test_create_and_read(client):
    created = client.post("/tasks", json={"title": "Napsat test"})
    assert created.status_code == 201
    task_id = created.json()["id"]

    response = client.get(f"/tasks/{task_id}")
    assert response.status_code == 200
    assert response.json()["title"] == "Napsat test"


def test_empty_title_is_rejected(client):
    response = client.post("/tasks", json={"title": ""})
    assert response.status_code == 422


def test_missing_task(client):
    assert client.get("/tasks/999").status_code == 404

TestClient(app) bez with nespustí lifespan, takže test na ostrý soubor tasks.db nesáhne. Když chceš otestovat i start aplikace, napiš with TestClient(app) as client:.

Mimo vývoj se aplikace spouští bez automatického restartu:

bash
fastapi run main.py --port 8000
# nebo přímo serverem
uvicorn main:app --host 0.0.0.0 --port 8000

Jak ji zabalit a dostat na server, je obsah další lekce, Docker a CI/CD.