Hogyan strukturálod egy nagy alkalmazást az APIRouter segítségével?

Question

Accepted Answer

**`APIRouter`** lehetővé teszi egy nagy FastAPI alkalmazás több modulra bontását — minden router a kapcsolódó végpontokat csoportosítja (például az összes `/users` útvonal), és a fő alkalmazás tartalmazza azokat. Ez tartja szervezettnek és karbantarthatónak a növekvő kódbázist.

## Router meghatározása a saját moduljában

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

Az `APIRouter` egy mini-alkalmazásként működik — azonos dekorátorokkal definiálja az útvonal-műveleteket rajta, és az `prefix` az összes nyitottra vonatkozik.

## Routerek belefoglalása a fő alkalmazásba

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

Az `app.include_router()` az egyes routerek végpontjait felcsatolja a fő alkalmazásba — az összes API-t moduláris részekből szereléséből.

## Egy jellemző projektstruktúra

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

Minden funkció/domain megkapja a saját router modulját — kapcsolódó útvonalak és a kódbázis rendezett maradnak.

## Router-szintű függőségek és konfiguráció

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

A routerek megosztott függőségeket hordozhatnak (például az admin auth szükséges az útvonalak egész csoportjához) — az összes végpontra egy időben alkalmazva.

## Miért fontos

Az `APIRouter` elengedhetetlen a triviális FastAPI alkalmazáson túl bárminek az elkészítéséhez — nélküle az összes végpont egy fájlban élne, ami kezelhetetlenné válik ahogy az API növekszik.

Annak megértése fontos a **kódszervezésre és karbantarthatóságra**: a végpontok funkció-alapú router modulokra bontása (felhasználók, elemek, hitelesítés) tartja a kapcsolódó kódot össze, a projektet navigálhatóvá teszi, és lehetővé teszi a csapatoknak, hogy függetlenül dolgozzanak a különböző területeken.

Az `prefix` és `tags` rendezettnek tartja az útvonalakat és a dokumentációt, és a **router-szintű függőségek** (például az admin hitelesítés megkövetelése az egész csoporthoz) tiszta, csoport-szintű viselkedést biztosítanak.

Ez a moduláris szerkezet normál gyakorlat a valós FastAPI alkalmazások számára, ami az `APIRouter`-t és a körülötte lévő projekt-szervezési mintákat olyan fontos, gyakorlatilag elengedhetetlen tudássá teszi skálázható, karbantartható API-k építéséhez.