كيف تنظم تطبيقًا كبيرًا باستخدام APIRouter؟

Question

Accepted Answer

**`APIRouter`** يسمح لك بتقسيم تطبيق FastAPI كبير إلى عدة وحدات — كل موجّه يجمّع الـ endpoints المرتبطة (مثلًا جميع مسارات `/users`)، والتطبيق الرئيسي يتضمنها. وهذا يحافظ على تنظيم قاعدة الكود المتنامية وسهولة صيانتها.

## تحديد موجّه في وحدته الخاصة

```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` مثل تطبيق مصغّر — تحدد path operations عليه بنفس الـ decorators، وـ `prefix` ينطبق على جميعها.

## تضمين الموجّهات في التطبيق الرئيسي

```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()` توصّل endpoints كل موجّه إلى التطبيق الرئيسي — مجمّعة الـ API الكاملة من أجزاء معيارية.

## هيكل مشروع نموذجي

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

كل ميزة/نطاق يحصل على وحدة موجّه خاصة به — الحفاظ على المسارات المرتبطة، وتنظيم قاعدة الكود بشكل جيد.

## التبعيات والإعدادات على مستوى الموجّه

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

يمكن للموجّهات أن تحمل تبعيات مشتركة (مثلًا طلب مصادقة مسؤول لمجموعة كاملة من المسارات) — تطبق على جميع endpoints الخاصة بها في الحال.

## لماذا يهم

`APIRouter` ضروري للبناء على أي شيء يتجاوز تطبيق FastAPI البسيط — بدونه، جميع الـ endpoints ستعيش في ملف واحد، وهذا يصبح غير قابل للإدارة مع نمو الـ API.
هم **تنظيم الكود والصيانة**: تقسيم الـ endpoints إلى وحدات موجّه مبنية على الميزات (مستخدمون، عناصر، مصادقة) يحافظ على الكود المرتبط معًا، يجعل المشروع سهل التنقل، ويسمح للفريق بالعمل على مناطق مختلفة بشكل مستقل.

`prefix` و `tags` تحافظ على المسارات والتوثيق منظمة، و **تبعيات على مستوى الموجّه** (مثل طلب مصادقة مسؤول لمجموعة كاملة) توفر سلوك نظيف على مستوى المجموعة.

هذا الهيكل المعياري هو ممارسة معيارية لتطبيقات FastAPI الحقيقية، مما يجعل `APIRouter` والأنماط حول تنظيم المشروع معرفة عملية ضرورية بشكل أساسي لبناء APIs قابل للتوسع والصيانة.