Kako strukturirate veliku aplikaciju s APIRouter?

Question

Accepted Answer

**`APIRouter`** vam omogućava da podijelite veliku FastAPI aplikaciju na više modula — svaki router grupiše povezane krajnje točke (na primjer, sve `/users` rute), a glavna aplikacija ih uključuje. To čini rastuću kodu bazu organiziranom i održavajućom.

## Definiranje routera u vlastitom 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): ...
```

`APIRouter` funkcionira kao mini-aplikacija — definirate operacije putanje na njemu istim dekoratorima, a `prefix` se primjenjuje na sve.

## Uključivanje routera u glavnu aplikaciju

```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 krajnje točke svakog routera u glavnu aplikaciju — skupljajući potpuni API iz modularnih dijelova.

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

Svaka značajka/domena dobija svoj router modul — čuvajući povezane rute i kod bazu dobro organiziranom.

## Rutinska ovisnost i konfiguracija

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

Routeri mogu nositi dijeljene ovisnosti (na primjer, zahtijevati auth administratora za cijelu grupu ruta) — primijenjene na sve njihove krajnje točke odjednom.

## Zašto je važno

`APIRouter` je bitan za izgradnju ičega izvan trivijalne FastAPI aplikacije — bez njega, sve krajnje točke bi živjele u jednoj datoteci, što postaje neupravljivim kako API raste.

Razumijevanje ga je važno za **organizaciju koda i održavljivost**: dijeljenje krajnjih točaka u module routera temeljene na značajkama (korisnici, stavke, auth) čuva srodnu kodu zajedno, čini projekt navigabilnim i omogućava timovima da rade na različitim dijelovima nezavisno.

`prefix` i `tags` čuvaju rute i dokumentaciju organiziranom, a **rutinske ovisnosti** (kao što je zahtijevanje auth administratora za cijelu grupu) pružaju čistu, skupinu-široku ponašanju.

Ova modularna struktura je standardna praksa za prave FastAPI aplikacije, čineći `APIRouter` i obrasce organizacije projekta oko njega važnom, praktički-nužnom znanjem za izgradnju skalabilnih, održavih API-ja.