Как установить коды состояния и заголовки?

Question

Accepted Answer

FastAPI по умолчанию возвращает `200 OK`, но вы управляете **кодом состояния** (через декоратор или объект response) и **заголовками** когда вам нужно другое поведение — важно для правильной семантики 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` позволяет вам устанавливать код состояния и заголовки **условно** во время выполнения.

## Почему это важно

```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(...)` — идиоматический способ — устанавливает состояние, сообщение JSON `detail` и дополнительные заголовки.

## Прямое возврат пользовательского Response

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

Правильные коды состояния и заголовки необходимы для создания корректных, хорошо работающих REST API — клиенты и инструменты полагаются на стандартную семантику HTTP (201 для создания, 404 для не найдено, 204 для отсутствия содержимого и т.д.), поэтому возврат правильного кода является частью контракта API высокого качества.

FastAPI дает вам чистое управление: код `status_code` по умолчанию на маршруте для стандартного случая, внедряемый объект `Response` для динамических кодов/заголовков и `HTTPException` как идиоматический способ сигнализировать об ошибках с соответствующим статусом и деталями JSON.

Понимание этих механизмов — и использование констант `status` для ясности — это повседневные знания для создания API, которые работают правильно и четко обмениваются информацией со своими потребителями.