كيف تحدد المسارات (عمليات المسار)؟

Question

Accepted Answer

في FastAPI، **عملية المسار** path operation هي مسار — دالة مزينة بمصمم HTTP method (`@app.get`, `@app.post`, إلخ) يتعامل مع الطلبات إلى مسار. يتم تسلسل قيمة الدالة تلقائياً إلى JSON.

## تحديد المسارات لكل طريقة HTTP

```python
from fastapi import FastAPI
app = FastAPI()

@app.get("/items")                # GET /items
def list_items():
    return [{"id": 1}, {"id": 2}]  # dict/list → automatically JSON-serialized

@app.get("/items/{item_id}")      # GET /items/5 — path parameter
def get_item(item_id: int):        # type hint converts "5" → int (and validates)
    return {"id": item_id}

@app.post("/items")               # POST /items
def create_item(item: Item):
    return item

@app.put("/items/{item_id}")      # PUT, PATCH, DELETE work the same way
@app.delete("/items/{item_id}")
def delete_item(item_id: int):
    return {"deleted": item_id}
```

كل مصمم يربط طريقة HTTP + مسار بمعالج. اسم الدالة متروك لك؛ المصمم يحدد المسار. يتم تسلسل القواميس/القوائم/نماذج Pydantic المرجعة تلقائياً إلى JSON — لا حاجة لـ `json.dumps` اليدوية.

## ترتيب المسارات المتداخلة مهم

```python
@app.get("/users/me")            # ✅ specific route FIRST
def read_me(): ...
@app.get("/users/{user_id}")     # dynamic AFTER — else "me" matches {user_id}
def read_user(user_id: int): ...
```

يطابق FastAPI المسارات بترتيب الإعلان، لذا ضع المسارات الثابتة قبل الديناميكية.

## بيانات العملية (تشغل المستندات)

```python
@app.get("/items", tags=["items"], summary="List items", status_code=200)
def list_items(): ...
```

معاملات المصمم (`tags`, `summary`, `status_code`, `response_model`) تكوّن السلوك وتثري المستندات المُنشأة تلقائياً.

## لماذا هذا مهم

عمليات المسار هي أساس كل تطبيق FastAPI — فهي تحدد نقاط نهاية API الخاصة بك وكيفية التعامل مع الطلبات.

فهم نمط المصمم لكل طريقة HTTP، أن القيم المرجعة يتم تسلسلها تلقائياً إلى JSON (بدون نمطية)، أن تلميحات النوع على المعاملات تدفع التحويل والتحقق، وأن ترتيب المسار مهم للمسارات المتداخلة هو معرفة أساسية يومية لبناء أي نقطة نهاية.

تغذي بيانات المصمم أيضاً المستندات التلقائية لـ FastAPI، مما يربط المسارات مباشرة بالمستندات.

هذا هو أول وأهم شيء يجب إتقانه في FastAPI.