Bagaimanakah anda menetapkan kod status dan header?

Question

Accepted Answer

FastAPI mengembalikan `200 OK` secara lalai, tetapi anda boleh mengawal **kod status** (melalui dekorator atau objek respons) dan **header** apabila anda memerlukan tingkah laku yang berbeza — penting untuk semantik REST yang betul.

## Menetapkan kod status lalai pada rute

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

Parameter dekorator `status_code` menetapkan status kejayaan lalai. Menggunakan pemalar `status` (cth. `status.HTTP_201_CREATED`) lebih jelas daripada nombor ajaib. Kod yang betul penting: `201` untuk dibuat, `204` untuk tiada kandungan, dll.

## Kod status dinamik dan header melalui objek 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
```

Menyuntikkan parameter `Response` membolehkan anda menetapkan kod status dan header **secara bersyarat** pada masa runtime.

## Ralat: raise 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
```

Untuk respons ralat, `raise HTTPException(...)` ialah cara idiomatik — ia menetapkan status, pesan JSON `detail`, dan header pilihan.

## Mengembalikan Response tersuai secara langsung

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

## Mengapa ini penting

Kod status dan header yang betul adalah penting untuk membina API REST yang betul dan berkelakuan baik — pelanggan dan alat bergantung pada semantik HTTP standard (201 untuk dibuat, 404 untuk tidak ditemui, 204 untuk tiada kandungan, dll.), jadi mengembalikan kod yang betul adalah bahagian daripada kontrak kualiti API.

FastAPI memberikan kawalan yang bersih: `status_code` lalai pada rute untuk kes umum, objek `Response` yang boleh disuntik untuk kod/header dinamik, dan `HTTPException` sebagai cara idiomatik untuk menandakan ralat dengan status yang sesuai dan detail JSON.

Memahami mekanisme ini — dan menggunakan pemalar `status` untuk kejelasan — adalah pengetahuan seharian untuk membina API yang berkelakuan dengan betul dan berkomunikasi dengan jelas dengan pengguna mereka.