كيف تعيّن رموز الحالة والرؤوس؟

Question

Accepted Answer

يُرجع FastAPI `200 OK` بشكل افتراضي، لكنك تتحكم في **رمز الحالة** (عبر الديكوريتور أو كائن الاستجابة) و**الرؤوس** عندما تحتاج إلى سلوك مختلف — أمر مهم لدلالات REST الصحيحة.

## تعيين رمز الحالة الافتراضي على المسار

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 for resource creation
def create_item(item: Item):
    return item                                             # returns with 201

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)  # 204
def delete_item(id: int):
    ...
```

معامل ديكوريتور `status_code` يعيّن حالة النجاح الافتراضية. استخدام ثوابت `status` (مثل `status.HTTP_201_CREATED`) أوضح من الأرقام السحرية. الرموز الصحيحة مهمة: `201` للإنشاء، `204` لعدم وجود محتوى، إلخ.

## رموز الحالة والرؤوس الديناميكية عبر كائن Response

```python
from fastapi import Response

@app.get("/items/{id}")
def get_item(id: int, response: Response):
    item = db.get(id)
    if not item:
        response.status_code = status.HTTP_404_NOT_FOUND   # set dynamically
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # set a custom header
    return item
```

حقن معامل `Response` يسمح لك بتعيين رمز الحالة والرؤوس **بشكل مشروط** في وقت التشغيل.

## الأخطاء: رفع HTTPException

```python
from fastapi import HTTPException

@app.get("/items/{id}")
def get_item(id: int):
    item = db.get(id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found",
                            headers={"X-Error": "NotFound"})   # status + detail + headers
    return item
```

للاستجابات الخطأ، `raise HTTPException(...)` هي الطريقة الاصطلاحية — فهي تعيّن الحالة، رسالة `detail` بصيغة JSON، ورؤوس اختيارية.

## إرجاع Response مخصص مباشرة

```python
from fastapi.responses import JSONResponse
return JSONResponse(content={...}, status_code=202, headers={"X-Custom": "v"})
```

## لماذا يهم

رموز الحالة والرؤوس الصحيحة ضرورية لبناء واجهات برمجية REST صحيحة وحسنة السلوك — العملاء والأدوات تعتمد على دلالات HTTP القياسية (`201` للإنشاء، `404` للعدم العثور عليه، `204` لعدم وجود محتوى، إلخ)، لذا فإن إرجاع الرمز الصحيح جزء من عقد API جيد.

يوفر FastAPI تحكماً نظيفاً: `status_code` افتراضي على المسار للحالة الشائعة، كائن `Response` قابل للحقن للرموز/الرؤوس الديناميكية، و`HTTPException` كطريقة اصطلاحية للإشارة إلى الأخطاء برمز مناسب وتفصيل JSON.

فهم هذه الآليات — واستخدام ثوابت `status` من أجل الوضوح — هو معرفة يومية لبناء واجهات برمجية تتصرف بشكل صحيح وتتواصل بوضوح مع مستهلكيها.