Kuinka strukturoit suuren sovelluksen APIRouter-ohjelmalla?

Question

Accepted Answer

**`APIRouter`** mahdollistaa suuren FastAPI-sovelluksen jakamisen useiksi moduuleiksi — jokainen reititin ryhmittelee toisiinsa liittyvät päätepisteet (esim. kaikki `/users`-reitit), ja pääsovellus sisältää ne. Tämä pitää kasvavan koodin perustan organisoituna ja ylläpidettävänä.

## Reitittimen määrittäminen omassa moduulissa

```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` toimii kuten mini-sovellus — määrität siihen path operations samoilla koristimilla ja `prefix` koskee kaikkia niistä.

## Reititinten sisällyttäminen pääsovellukseen

```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()` liittää jokaisen reitittimen päätepisteet pääsovellukseen — kokoaa koko API:n modulaareista osista.

## Tyypillinen projektirakenteesi

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

Jokainen ominaisuus/alue saa oman reititin moduulin — pitää toisiinsa liittyvät reitit ja koodin perustan hyvin organisoituina.

## Reitittimen tason riippuvuudet ja konfiguraatio

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

Reitittimet voivat kantaa jaettuja riippuvuuksia (esim. vaatia admin-todennusta koko reittiryhmälle) — sovellettu kaikkiin niiden päätepisteeseisiin kerralla.

## Miksi se on tärkeää

`APIRouter` on välttämätön kaikelle muulle kuin triviaaliille FastAPI-sovellukselle — ilman sitä kaikki päätepisteet asuisivat yhdessä tiedostossa, mikä muuttuu hallitsemattomaksi API:n kasvaessa.

Sen ymmärtäminen on tärkeää **koodin organisoinnille ja ylläpidettävyydelle**: päätepisteiden jakaminen ominaisuuspohjaisiin reititin moduuleihin (käyttäjät, kohteet, todennus) pitää liittyvän koodin yhdessä, tekee projektista navigoitavan ja antaa tiimeille mahdollisuuden työskennellä eri alueilla itsenäisesti.

`prefix` ja `tags` pitävät reitit ja dokumentaation organisoituna, ja **reitittimen tason riippuvuudet** (kuten vaatia admin-todennusta koko reittiryhmälle) tarjoavat puhtaat, ryhmänlaajuiset käyttäytymismuodot.

Tämä modulaarinen rakenne on vakiokäytäntö oikeille FastAPI-sovelluksille, mikä tekee `APIRouter`-ohjelmasta ja projektinjärjestelymalleista sen ympärillä tärkeitä, käytännössä olennaisia tietoja skaalautuvien ja ylläpidettävien API-ohjelmien rakentamiseen.