Bagaimanakah anda menstruktur aplikasi besar dengan APIRouter?

Question

Accepted Answer

**`APIRouter`** memungkinkan anda membahagi aplikasi FastAPI besar kepada beberapa modul — setiap router mengelompokkan titik akhir yang berkaitan (contohnya, semua rute `/users`), dan aplikasi utama memasukkannya. Ini membuat pangkalan kod yang berkembang tetap teratur dan mudah diselenggarakan.

## Menentukan router dalam modulnya sendiri

```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` berfungsi seperti mini-app — anda menentukan operasi path padanya dengan penyamarataan yang sama, dan `prefix` diterapkan kepada semuanya.

## Memasukkan router dalam aplikasi utama

```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()` memasang titik akhir setiap router ke dalam aplikasi utama — mengumpulkan API penuh dari potongan modular.

## Struktur projek yang biasa

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

Setiap fitur/domain mendapat modul router sendirinya — mengekalkan rute yang berkaitan dan pangkalan kod yang teratur dengan baik.

## Kebergantungan dan konfigurasi peringkat 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
```

Router boleh membawa kebergantungan bersama (contohnya, memerlukan pengesahan pentadbir untuk seluruh kumpulan rute) — digunakan untuk semua titik akhir mereka sekaligus.

## Mengapa ini penting

`APIRouter` adalah penting untuk membina apa-apa di luar aplikasi FastAPI yang remeh — tanpanya, semua titik akhir akan berada dalam satu fail, yang menjadi tidak terurus apabila API berkembang.

Pemahaman ini penting untuk **organisasi kod dan kemudahan penyelenggaraan**: membahagi titik akhir kepada modul router berasaskan ciri (pengguna, item, pengesahan) mengekalkan kod yang berkaitan bersama, menjadikan projek mudah dinavigasi, dan membenarkan pasukan bekerja di kawasan berbeza secara bebas.

`prefix` dan `tags` mengekalkan rute dan dokumentasi teratur, dan **kebergantungan peringkat router** (seperti memerlukan pengesahan pentadbir untuk seluruh kumpulan) memberikan kelakuan bersih peringkat kumpulan.

Struktur modular ini adalah amalan piawai untuk aplikasi FastAPI sebenar, menjadikan `APIRouter` dan corak organisasi projek di sekelilingnya pengetahuan penting, secara praktikal penting untuk membina API yang boleh diskalakan dan mudah diselenggarakan.