Cum structurezi o aplicație mare cu APIRouter?

Question

Accepted Answer

**`APIRouter`** te permite să împarți o aplicație FastAPI mare în mai multe module — fiecare router grupează endpoint-uri corelate (de ex. toate rutele `/users`), iar aplicația principală le include. Acest lucru menține o bază de cod în creștere organizată și ușor de întreținut.

## Definirea unui router în propriul 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): ...
```

Un `APIRouter` funcționează ca o mini-aplicație — definești operații de cale pe el cu aceleași decoratori, și un `prefix` se aplică tuturor lor.

## Includerea routerelor în aplicația principală

```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()` montează endpoint-urile fiecărui router în aplicația principală — asamblând API-ul complet din piese modulare.

## O structură de proiect tipică

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

Fiecare caracteristică/domeniu primește propriul modul router — păstrând rutele corelate și baza de cod bine organizate.

## Dependențe și configurare la nivel de router

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

Routerele pot purta dependențe comune (de ex. necesită autentificare admin pentru un grup întreg de rute) — aplicate tuturor endpoint-urilor lor simultan.

## De ce contează

`APIRouter` este esențial pentru construirea oricărui lucru dincolo de o aplicație FastAPI banală — fără el, toate endpoint-urile ar trăi într-un singur fișier, ceea ce devine necontrolabil pe măsură ce API-ul crește.

Înțelegerea acestuia este importantă pentru **organizarea codului și ușurința întreținerii**: împărțirea endpoint-urilor în module router bazate pe caracteristici (utilizatori, articole, autentificare) ține codul corelat împreună, face proiectul ușor de navigat și permite echipelor să lucreze pe diferite zone în mod independent.

`prefix` și `tags` menține rutele și documentația organizate, iar **dependențele la nivel de router** (cum ar fi necesitatea autentificării admin pentru un grup întreg) oferă comportament curat și la scară de grup.

Această structură modulară este practica standard pentru aplicațiile FastAPI reale, făcând `APIRouter` și modelele de organizare a proiectului din jurul acestuia cunoștințe importante, practic esențiale pentru construirea API-urilor scalabile și ușor de întreținut.