상태 코드와 헤더를 어떻게 설정합니까?

Question

Accepted Answer

FastAPI는 기본적으로 `200 OK`를 반환하지만, 다른 동작이 필요할 때는 **상태 코드**(데코레이터 또는 응답 객체를 통해)와 **헤더**를 제어할 수 있습니다. 이는 올바른 REST 의미론에 중요합니다.

## 라우트에 기본 상태 코드 설정

```python
from fastapi import status

@app.post("/items", status_code=status.HTTP_201_CREATED)   # 리소스 생성에는 201
def create_item(item: Item):
    return item                                             # 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   # 동적으로 설정
        return {"error": "not found"}
    response.headers["X-Custom"] = "value"                  # 커스텀 헤더 설정
    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"})   # 상태 + detail + 헤더
    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` 객체, 그리고 적절한 상태와 JSON detail로 오류를 신호하는 관용적인 방법인 `HTTPException`.

이러한 메커니즘을 이해하고—명확성을 위해 `status` 상수를 사용하는 것—은 사용자와 올바르게 동작하고 명확하게 소통하는 API를 구축하기 위한 일상 지식입니다.