Jak strukturyzować dużą aplikację za pomocą APIRouter?

Question

Accepted Answer

**`APIRouter`** pozwala podzielić dużą aplikację FastAPI na wiele modułów — każdy router grupuje powiązane endpointy (np. wszystkie trasy `/users`), a główna aplikacja je zawiera. To utrzymuje rosnącą bazę kodu zorganizowaną i łatwą w utrzymaniu.

## Definiowanie routera w osobnym module

```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` działa jak mini-aplikacja — definiujesz path operations na nim za pomocą tych samych dekoratorów, a `prefix` stosuje się do wszystkich z nich.

## Dołączanie routerów do głównej aplikacji

```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()` montuje endpointy każdego routera w głównej aplikacji — składając pełny API z modułowych części.

## Typowa 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żda funkcjonalność/domena otrzymuje swój własny moduł routera — utrzymując powiązane trasy i bazę kodu dobrze zorganizowaną.

## Zależności i konfiguracja na poziomie routera

```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 mogą zawierać wspólne zależności (np. wymaganie auth admina dla całej grupy tras) — stosowane do wszystkich ich endpointów jednocześnie.

## Dlaczego to ważne

`APIRouter` jest niezbędny dla budowania czegoś więcej niż trywialnej aplikacji FastAPI — bez niego wszystkie endpointy byłyby w jednym pliku, co staje się niemożliwe do zarządzania w miarę rozwoju API.

Zrozumienie go jest ważne dla **organizacji kodu i utrzymywalności**: podzielenie endpointów na moduły routerów oparte na funkcjonalnościach (użytkownicy, przedmioty, autentykacja) utrzymuje powiązany kod razem, czyni projekt nawigacyjny i pozwala zespołom pracować niezależnie w różnych obszarach.

`prefix` i `tags` utrzymują trasy i dokumentację zorganizowaną, a **zależności na poziomie routera** (jak wymaganie auth admina dla całej grupy) zapewniają czysty, grupowy przy zachowaniu.

Ta modularna struktura jest standardową praktyką dla rzeczywistych aplikacji FastAPI, czyniąc `APIRouter` i wzorce organizacji projektów wokół niego ważną, praktycznie niezbędną wiedzą dla budowania skalowalnych, łatwych w utrzymaniu API.