📦 FastAPI에서의 Request와 Response 완벽 이해

🕒 약 2분 읽는 데 소요됩니다

이전 글 보기(FastAPI 라우팅 완전 정복)

– 데이터는 오고, 응답은 간다: Pydantic, Request Body, Response 모델 완전정복

“API의 진짜 힘은 데이터에서 나온다.”
클라이언트에서 서버로 데이터를 보내고, 서버는 그에 맞춰 응답을 돌려준다. 이것이 API의 기본 메커니즘이고, FastAPI는 이걸 가장 안전하고, 가장 빠르게 구현할 수 있는 프레임워크다.

이번 시간에는 FastAPI의 세 가지 핵심 기능에 대해 배워본다:

• Pydantic을 활용한 데이터 검증
• Request Body를 통해 클라이언트로부터 데이터 받기
• 응답을 명확하게 만드는 Response 모델 정의

---

✅ Pydantic을 활용한 데이터 검증

FastAPI는 내부적으로 Pydantic이라는 데이터 검증 라이브러리를 사용한다. 이 라이브러리를 통해 입력 데이터의 유효성을 자동으로 검사하고, 올바르지 않은 데이터는 422 오류와 함께 친절한 메시지를 제공한다.

1. 기본 사용 예

from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    in_stock: bool

• Item이라는 클래스를 정의했지만, 단순한 클래스가 아니다.
• 이건 데이터 모델이자 동시에 입력 검증 도구다.
• 클라이언트가 보낸 JSON 데이터가 이 모델과 일치하지 않으면 자동으로 거부된다.

2. 자동 타입 검사

• name에는 문자열만 들어와야 한다.
• price에는 숫자(float)가 와야 한다.
• in_stock에는 Boolean 값만 허용된다.

예를 들어 클라이언트가 "price": "cheap"라고 보냈다면? → FastAPI는 바로 오류를 반환한다.

---

📥 Request Body 처리하기

이제 본격적으로 POST 요청을 통해 클라이언트가 보낸 JSON 데이터를 받는 방법을 살펴보자.

1. POST 요청 예시

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None

@app.post("/items/")
def create_item(item: Item):
    return {"received_item": item}

2. 동작 원리

• 클라이언트가 JSON 형식으로 데이터를 보내면 FastAPI는 Item 모델을 기준으로 유효성을 검사한다.
• 유효한 경우 item 인자로 자동 파싱되어 함수에 전달된다.
• 응답은 동일한 구조로 JSON으로 반환된다.

3. 테스트 방법

1. 서버 실행:

uvicorn main:app --reload

2. Swagger 접속: http://127.0.0.1:8000/docs

3. /items/ POST 요청 실행
JSON 입력 예시:

{ "name": "Monitor", "price": 219.99, "description": "24-inch Full HD monitor" }

4. 응답 결과:

{ "received_item": { "name": "Monitor", "price": 219.99, "description": "24-inch Full HD monitor" } }

4. 필드 기본값 및 선택값

• description: str | None = None 은 선택 항목임
• 입력에서 빠져도 오류 나지 않음
• 타입 힌트를 정확히 써주면 자동으로 문서화됨

---

📤 Response 모델 정의

API 응답을 개발자 마음대로 구성하면 유지보수가 어렵고, 문서화도 어려워진다. 그래서 FastAPI는 응답 형태도 Pydantic 모델로 정의할 수 있도록 지원한다.

1. 응답 모델 지정 예

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    description: str | None = None

class ItemResponse(BaseModel):
    name: str
    price: float

@app.post("/items/", response_model=ItemResponse)
def create_item(item: Item):
    return item

2. 응답 모델이 하는 일

• 클라이언트에게는 name과 price만 반환되고, description은 제외됨
• 내부 로직에서는 여전히 전체 데이터를 사용할 수 있음

즉, 내부에서는 필요한 필드 모두 처리하되, 클라이언트에는 필요한 정보만 전달할 수 있게 된다.

3. 보안, UX 측면에서도 유리

• 민감 정보(ex. 비밀번호)는 응답에서 자동으로 제외 가능
• 프론트엔드 입장에서 필요한 정보만 받아 UX 개선 가능

---

💡 보너스: 응답 상태 코드 지정하기

FastAPI는 기본적으로 200 또는 201 등의 상태 코드를 자동으로 처리하지만, 명시적으로 지정할 수도 있다.

from fastapi import status

@app.post("/items/", response_model=ItemResponse, status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    return item

• status.HTTP_201_CREATED → 201 Created 응답
• 상태 코드를 명확하게 지정해줌으로써 API 의도를 더 잘 표현할 수 있다.

---

🧾 정리: 데이터 흐름을 제어하는 가장 확실한 방법

지금까지 FastAPI에서 데이터가 어떻게 들어오고 나가는지를 살펴봤다.

개념	기능	설명
Pydantic	입력 검증	JSON 데이터를 Python 객체로 자동 변환 & 검증
Request Body	입력 처리	POST/PUT 등의 요청 본문을 처리
Response Model	출력 제어	응답 구조를 정의해 일관성 확보
상태 코드	응답 의미	HTTP 표준에 맞는 의미 전달

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/