Jak strukturujete velkou aplikaci pomocí APIRouter?

Question

Accepted Answer

**`APIRouter`** vám umožňuje rozdělit velkou FastAPI aplikaci do více modulů — každý router seskupuje související endpoints (např. všechny trasy `/users`), a hlavní aplikace je zahrnuje. To udržuje rostoucí kódovou základnu organizovanou a snadno udržitelnou.

## Definování routeru ve vlastním modulu

```python
# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # all routes here start with /users
    tags=["users"],           # grouped under "users" in the docs
)

@router.get("/")              # GET /users/
def list_users(): ...

@router.get("/{user_id}")     # GET /users/{user_id}
def get_user(user_id: int): ...
```

`APIRouter` funguje jako mini-aplikace — definujete na ní path operations se stejnými dekorátory a `prefix` se aplikuje na všechny z nich.

## Zahrnutí routerů do hlavní aplikace

```python
# main.py
from fastapi import FastAPI
from routers import users, items, auth

app = FastAPI()
app.include_router(users.router)     # mounts /users/* endpoints
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()` připojí endpoints každého routeru do hlavní aplikace — sestaví úplné API z modulárních kusů.

## Typická struktura projektu

```text
app/
  main.py              # creates the app, includes routers
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
    auth.py            # APIRouter for /auth
  models.py            # Pydantic models
  database.py          # DB setup
  dependencies.py      # shared dependencies
```

Každá funkce/doména dostane svůj vlastní modul routeru — udržuje související trasy a kódovou základnu dobře organizovanou.

## Závislosti a konfigurace na úrovni routeru

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # apply a dependency to ALL routes in the router
)
# you can also nest routers via include_router on a router
```

Routery mohou nést sdílené závislosti (např. vyžadovat autentizaci administrátora pro celou skupinu tras) — aplikují se na všechny jejich endpoints najednou.

## Proč je to důležité

`APIRouter` je nezbytný pro stavbu čehokoliv víc než triviální FastAPI aplikace — bez něj by všechny endpoints žily v jednom souboru, což se stane nezvládnutelným, jak API roste.

Rozvíjení tohoto porozumění je důležité pro **organizaci kódu a udržovatelnost**: rozdělení endpoints do modulů routeru založených na funkcích (uživatelé, položky, autentizace) udržuje související kód pohromadě, činí projekt navigovatelným a umožňuje týmům pracovat na různých oblastech nezávisle.

`prefix` a `tags` udržují trasy a dokumentaci organizovanou a **závislosti na úrovni routeru** (jako vyžadování autentizace administrátora pro celou skupinu) poskytují čisté chování v rámci skupiny.

Tato modulární struktura je standardní praxí pro skutečné FastAPI aplikace, což činí `APIRouter` a vzory organizace projektu kolem něj důležitou, prakticky nezbytnou znalostí pro budování škálovatelných a udržitelných API.