Kako strukturirate večjo aplikacijo z APIRouter?

Question

Accepted Answer

**`APIRouter`** vam omogoča razcepitev velike FastAPI aplikacije na več modulov — vsak usmerilnik združi sorodne končne točke (npr. vse `/users` poti), glavna aplikacija pa jih vključi. To ohrani rastočo kodno bazo organizirano in vzdrževalno.

## Določanje usmernika v svojem 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): ...
```

An `APIRouter` deluje kot mini-aplikacija — na njem definirate operacije poti z istimi dekoratorji, `prefix` pa se uporabi za vse od njih.

## Vključevanje usmernikov v glavno aplikacijo

```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()` montira končne točke vsakega usmernika v glavno aplikacijo — sestavi celoten API iz modularnih kosov.

## Tipična struktura projekta

```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
```

Vsaka funkcionalnost/domena dobi svoj modul usmernika — sorodne poti so skupaj in kodno bazo je dobro organizirana.

## Odvisnosti in konfiguracija na ravni usmernika

```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
```

Usmerniki lahko nosijo skupne odvisnosti (npr. zahtevajo admin avtentifikacijo za celotno skupino poti) — uporabljene za vse njihove končne točke naenkrat.

## Zakaj je to pomembno

`APIRouter` je nujno potreben za gradnjo česa več kot trivialnih FastAPI aplikacij — brez njega bi vse končne točke živele v eni datoteki, kar postane neobvladljivo, ko API raste.

Razumevanje je pomembno za **organizacijo kode in vzdrževljivost**: razdelitev končnih točk v module usmernikov na osnovi funkcionalnosti (uporabniki, elementi, avtentifikacija) drži sorodna koda skupaj, naredi projekt prezentabilnega in omogoči timom, da delujejo na različnih področjih neodvisno.

`prefix` in `tags` держе poti in dokumentacijo organizirane, **odvisnosti na ravni usmernika** (kot je zahtevanje admin avtentifikacije za celotno skupino) pa zagotavljajo čisto, skupinsko vedenje.

Ta modularna struktura je standardna praksa za prave FastAPI aplikacije, kar naredi `APIRouter` in vzorce organizacije projekta okoli njega kot pomembno, praktično nujno znanje za gradnjo razširljivih, vzdrževanih API-jev.