Büyük bir uygulamayı APIRouter ile nasıl yapılandırırsınız?

Question

Accepted Answer

**`APIRouter`** büyük bir FastAPI uygulamasını birden fazla modüle bölmenizi sağlar — her router ilgili endpoint'leri gruplandırır (örn. tüm `/users` rotaları), ve ana uygulama bunları içerir. Bu, büyüyen bir kod tabanını organize ve bakımlanabilir tutar.

## Bir router'ı kendi modülünde tanımlama

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

Bir `APIRouter` mini bir uygulama gibi çalışır — aynı dekoratörleri kullanarak path operasyonlarını tanımlarsınız, ve bir `prefix` tüm bunlara uygulanır.

## Router'ları ana uygulamaya dahil etme

```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()` her router'ın endpoint'lerini ana uygulamaya monte eder — tam API'yi modüler parçalardan birleştirir.

## Tipik bir proje yapısı

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

Her özellik/alan kendi router modülünü alır — ilgili rotaları ve kod tabanını iyi organize tutarak.

## Router seviyesi bağımlılıklar ve yapılandırma

```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'lar paylaşılan bağımlılıklar taşıyabilir (örn. bir rota grubunun tamamı için admin yetkilendirmesi gerektir) — tüm endpoint'lerine aynı anda uygulanır.

## Neden önemli

`APIRouter` önemsiz olmayan bir FastAPI uygulaması oluşturmak için gereklidir — onsuz, tüm endpoint'ler bir dosyada yaşardı, bu API büyüdükçe yönetilemez hale gelir.

Bunu anlamak **kod organizasyonu ve bakımlanabilirlik** için önemlidir: endpoint'leri özellik tabanlı router modüllerine bölmek (users, items, auth) ilgili kodu bir arada tutar, projeyi gezinebilir hale getirir ve takımların bağımsız olarak farklı alanlarda çalışmasını sağlar.

`prefix` ve `tags` rotaları ve belgeleri organize tutarken, **router seviyesi bağımlılıklar** (bir rota grubu için admin yetkilendirmesi gerektirmek gibi) temiz, gruba geniş davranış sağlar.

Bu modüler yapı gerçek FastAPI uygulamaları için standart uygulamadır, `APIRouter` ve etrafındaki proje-organizasyon desenlerini ölçeklenebilir, bakımlanabilir API'ler oluşturmak için önemli, pratik olarak gerekli bilgi haline getirir.