response_model은 무엇을 위한 것입니까?

Question

Accepted Answer

**`response_model`** 매개변수는 엔드포인트 응답의 형태를 선언합니다. FastAPI는 이를 사용해 반환된 데이터를 **검증, 필터링, 직렬화**하고, API 문서에 응답을 문서화합니다. 가장 중요한 역할은 의도한 필드만 노출되도록 보장하는 것입니다(예: 비밀번호를 절대 유출하지 않음).

## 문제: 민감한 필드 유출

```python
class User(BaseModel):
    name: str
    email: str
    password: str        # ⚠️ 응답에 절대 포함되어서는 안 됨!

@app.get("/users/{id}")
def get_user(id: int) -> User:
    return db.get_user(id)   # 전체 객체를 반환하면 비밀번호가 노출됨
```

## 해결책: 별도의 응답 모델

```python
class UserOut(BaseModel):    # 안전한 공개 형태 — 비밀번호 없음
    name: str
    email: str

@app.get("/users/{id}", response_model=UserOut)
def get_user(id: int):
    return db.get_user(id)   # 전체 user를 반환하지만 FastAPI가 UserOut으로 필터링함
# 응답 → { "name": "...", "email": "..." }  — 비밀번호가 자동으로 제거됨
```

`response_model=UserOut`을 지정하면, FastAPI는 반환한 것을 가져와 `UserOut`에 선언된 필드로만 **필터링**합니다. 따라서 전체 객체를 반환하더라도 비밀번호(및 기타 추가 필드)는 응답에서 제거됩니다.

## response_model이 하는 일

```text
✓ 출력을 선언된 필드로만 필터링 (민감한 데이터 숨김에 핵심)
✓ 응답이 선언된 schema와 일치하는지 검증 (실수 포착)
✓ 데이터를 JSON으로 올바르게 직렬화
✓ OpenAPI/Swagger 문서에 응답 형태를 문서화
```

## 현대적 대안: 반환 타입 어노테이션

```python
@app.get("/users/{id}")
def get_user(id: int) -> UserOut:    # -> 반환 타입이 response_model처럼 동작함
    return db.get_user(id)
# response_model_exclude_unset=True → 명시적으로 설정되지 않은 필드 생략
```

## 왜 중요한가

`response_model`은 **보안**과 깔끔한 API 설계 모두에 중요합니다.

가장 핵심적인 역할은 우발적인 데이터 유출을 방지하는 것입니다. 응답에 포함되어야 할 필드를 정확히 선언함으로써, 코드가 전체 데이터베이스 객체를 반환하더라도 FastAPI는 나머지 모든 것(비밀번호 해시, 내부 플래그, 토큰 등)을 걸러내어, 흔하고 심각한 취약점을 제거합니다.

그 외에도 응답을 선언된 schema에 대해 검증하고(잘못된 형태를 반환하는 버그 포착), 올바른 직렬화를 보장하며, 자동 생성 API 문서에 응답을 문서화합니다.

별도의 입력 및 출력 모델을 사용하는 패턴(노출 대상을 `response_model`로 제어)은 안전하고 잘 정의된 API를 위한 모범 사례이므로, 데이터를 반환하는 모든 엔드포인트에 대해 중요한 지식입니다.