📦 Request Body

FastAPI에서 Request Body는 클라이언트가 서버로 보내는 “실제 데이터”를 담는 영역이다.

---

📚 1. Request Body란?

HTTP 요청(Request)은 크게 두 부분으로 나뉜다.

구성	역할
Header	메타 정보 (인증, 타입 등)
Body	실제 데이터

예를 들면:

• 회원 가입 정보
• 게시글 내용
• 상품 생성 데이터

등은 모두 Request Body로 전달된다.

---

⚠️ HTTP 메서드와 Request Body

Request Body는 아무 요청에나 쓰이지 않는다.

HTTP 메서드	Request Body 사용
GET	❌ 권장되지 않음
POST	✅ 사용
PUT	✅ 사용
PATCH	✅ 사용
DELETE	⚠️ 경우에 따라 사용

---

🧪 2. Request Body 직접 체험

📁 프로젝트 구조

fastapi-body/
 ├─ main.py
 └─ requirements.txt

📦 패키지 설치

# requirements.txt
fastapi[standard]
pydantic

pip install -r requirements.txt

✍️ 코드 작성

FastAPI에서는 Pydantic 모델을 사용해 Request Body 구조를 정의한다.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel

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

app = FastAPI()

@app.post("/items/")
async def create_item(item: Item):
    return {
        "item": item,
        "status": "done"
    }

📝 Swagger UI에서 실습해보기
해당 JSON을 Request Body에 입력

{
    "name": "노트북",
    "description": "개발용 맥북",
    "price": 2500000,
    "tax": 250000
}

결과:
응답에 쓰였던 item 객체가 json으로 직렬화 되었다.

---

🧠 Pydantic 모델

Pydantic이란
Pydantic은 Python의 데이터 검증 라이브러리로,"pedantic(까다로운)"이라는 단어에서 유래했다.
데이터 타입을 까다롭게 검사해준다는 의미를 담고 있음.

FastAPI는 Pydantic을 사용해서 Request Body의 데이터를 자동으로 검증한다.

모델 정의:

from pydantic import BaseModel


class Item(BaseModel):
    name: str                          # 필수: 타입에 기본값이 없으면 요청 할 때 값을 반드시 입력받아야 통과됨.
    description: str | None = None     # 선택: 타입에 기본값이 있기 때문.
    price: float                       # 필수
    tax: float | None = None           # 선택

📌 필수 필드 vs 선택 필드

선언 방식	의미
name: str	필수 (반드시 전달)
description: str | None = None	선택 (없어도 OK)

---

🧠 모델 데이터 활용하기

Pydantic 모델을 딕셔너리로 변환하는 것도 가능하다.
따라서 원하는 필드를 자유롭게 추가할 수 있어서 유연하게 사용할 수 있다.

@app.post("/items/")
async def create_item(item: Item):
    item_dict = item.model_dump()                            # 1. 모델 → 딕셔너리 변환
    if item.tax is not None:
        price_with_tax = item.price + item.tax               # 2. 모델 속성으로 계산
        item_dict.update({"price_with_tax": price_with_tax}) # 3. 새 필드 추가
    return item_dict									     # 4. 확장된 딕셔너리 반환

📌 왜 바로 dict로 안 받을까?

방식	문제점
dict	자동완성 ❌, 타입 안정성 ❌
Pydantic 모델	자동완성 ✅, 타입 안정성 ✅

item.price 처럼 점(.) 접근이 가능하고
IDE가 타입을 이해하기 때문에 실수가 급격히 줄어든다.

---

🔄 Request Body 내부 처리 흐름

요청 JSON
 ↓
FastAPI 수신
 ↓
Pydantic 모델 매핑
 ↓
타입 변환 + 검증
 ↓
함수 실행
 ↓
Response Body 반환

---

🧠 Path · Query · Body 조합 규칙

FastAPI는 파라미터의 위치와 타입만 보고 어디서 데이터를 가져올지 자동으로 판단한다.

📌 Path + Body

@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):
    return {
        "item_id": item_id,
        **item.model_dump()
    }

📌 Path + Query + Body

@app.put("/items/{item_id}")
async def update_item(
    item_id: int,
    item: Item,
    q: str | None = None
):
    result = {
        "item_id": item_id,
        **item.model_dump()
    }
    if q:
        result["q"] = q
    return result

---

🧭 FastAPI 파라미터 판별 규칙 (중요)

조건	판별 결과
URL 경로에 포함	Path Parameter
Pydantic 모델 타입	Request Body
단순 타입 (int, str 등)	Query Parameter

---

📌 전체 흐름 요약

Client JSON
 ↓
FastAPI 수신
 ↓
Pydantic 모델 매핑
 ↓
타입 변환 + 검증
 ↓
비즈니스 로직
 ↓
Response Body

---

✅ 최종 정리

• Request Body는 실제 데이터 전달 영역
• Pydantic 모델은 데이터 계약서
• 기본값 유무로 필수/선택 판단
• 검증 · 파싱 · 문서화를 FastAPI가 자동 처리