Wie strukturieren Sie eine große App mit APIRouter?

Question

Accepted Answer

**`APIRouter`** ermöglicht es dir, eine große FastAPI-App in mehrere Module aufzuteilen — jeder Router gruppiert verwandte Endpoints (z. B. alle `/users`-Routen), und die Hauptapp bindet sie ein. Dies hält eine wachsende Codebasis organisiert und wartbar.

## Definieren eines Routers in seinem eigenen Modul

```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): ...
```

Ein `APIRouter` funktioniert wie eine Mini-App — du definierst Path Operations darauf mit den gleichen Dekoratoren, und ein `prefix` wird auf alle angewendet.

## Einbinden von Routern in die Hauptapp

```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()` bindet die Endpoints jedes Routers in die Hauptapp ein — setzt die vollständige API aus modularen Teilen zusammen.

## Eine typische Projektstruktur

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

Jedes Feature/jede Domäne erhält sein eigenes Router-Modul — hält verwandte Routen und die Codebasis gut organisiert.

## Router-Ebenen-Abhängigkeiten und Konfiguration

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

Router können gemeinsame Abhängigkeiten tragen (z. B. Admin-Auth für eine ganze Gruppe von Routen verlangen) — angewendet auf alle ihre Endpoints auf einmal.

## Warum es wichtig ist

`APIRouter` ist essentiell für alles über eine triviale FastAPI-App hinaus — ohne sie würden alle Endpoints in einer Datei leben, was unmöglich zu handhaben wird, während die API wächst.

Das Verstehen davon ist wichtig für **Code-Organisation und Wartbarkeit**: Die Aufteilung von Endpoints in feature-basierte Router-Module (Benutzer, Artikel, Auth) hält verwandten Code zusammen, macht das Projekt navigierbar und ermöglicht Teams, unabhängig an verschiedenen Bereichen zu arbeiten.

`prefix` und `tags` halten Routen und Dokumentation organisiert, und **Router-Ebenen-Abhängigkeiten** (wie Admin-Auth für eine ganze Gruppe erforderlich) bieten sauberes, gruppenweites Verhalten.

Diese modulare Struktur ist Standardpraxis für echte FastAPI-Anwendungen, was `APIRouter` und die Muster der Projektorganisation darum zu wichtigem, praktisch unverzichtbarem Wissen für die Erstellung skalierbarer, wartbarer APIs macht.