Làm thế nào để đặt status code và header?

Question

Accepted Answer

FastAPI trả về `200 OK` mặc định, nhưng bạn kiểm soát **status code** (qua decorator hoặc đối tượng response) và **header** khi cần hành vi khác — quan trọng cho ngữ nghĩa REST đúng đắn.

## Đặt status code mặc định trên route

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 201 cho việc tạo resource
def create_item(item: Item):
    return item                                             # trả về với 201

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

Tham số decorator `status_code` đặt status thành công mặc định. Dùng các hằng `status` (ví dụ `status.HTTP_201_CREATED`) rõ ràng hơn các con số ma thuật. Code đúng quan trọng: `201` cho đã tạo, `204` cho không nội dung, v.v.

## Status code và header động qua đối tượng 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   # đặt động
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # đặt một header tùy chỉnh
    return item
```

Tiêm một tham số `Response` cho phép bạn đặt status code và header **có điều kiện** tại thời điểm chạy.

## Lỗi: 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 + header
    return item
```

Với response lỗi, `raise HTTPException(...)` là cách idiomatic — nó đặt status, một thông báo JSON `detail`, và các header tùy chọn.

## Trả về một Response tùy chỉnh trực tiếp

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

## Tại sao điều này quan trọng

Status code và header đúng đắn là thiết yếu để xây dựng REST API đúng đắn, hành xử tốt — client và công cụ dựa vào ngữ nghĩa HTTP chuẩn (201 cho đã tạo, 404 cho không tìm thấy, 204 cho không nội dung, v.v.), vì vậy trả về đúng code là một phần của contract API chất lượng.

FastAPI cho bạn kiểm soát gọn gàng: một `status_code` mặc định trên route cho trường hợp phổ biến, đối tượng `Response` có thể tiêm cho code/header động, và `HTTPException` là cách idiomatic để báo hiệu lỗi với status thích hợp và một detail JSON.

Hiểu các cơ chế này — và dùng các hằng `status` để rõ ràng — là kiến thức hằng ngày để xây dựng API hành xử đúng và giao tiếp rõ ràng với người tiêu thụ.