🚀 FastAPI 요청과 응답 처리 흐름 완전 정리
이 글에서는 FastAPI에서 사용하는 다양한 요청 처리 방식과 응답 포맷을 코드 흐름에 따라 단계별로 정리합니다. 실전에서 많이 사용되는 Path, Query, Body, Form, File, HTML, 텍스트 응답까지 모두 포함합니다.
1️⃣ Path Parameter 사용하기
@router.get("/items/{item_id}")
def get_item_handler(item_id: int = Path(ge=1)):
return {"message": item_id}- 1️⃣ @router.get("/items/{item_id}")
- 이 함수는 GET /items/123처럼 요청이 들어왔을 때 실행됩니다.
- 즉, URL 경로에 있는 값을 받아오는 API입니다.
2️⃣ item_id: int = Path(ge=1)- item_id는 경로(path) 안에 있는 숫자입니다.
- int: 타입 힌트로, 정수만 허용합니다.
- Path(ge=1):
- ge=1 → greater than or equal → 1 이상만 허용
- 즉, 0, -1, -100 등은 자동으로 422 에러를 반환합니다.
- Path()는 Path Parameter 전용의 유효성 검사 도구입니다.
👉 타입을 명시하면 자동으로 유효성 검사를 수행합니다.
2️⃣ Query Parameter와 유효성 검사
@router.get("")
def get_items_handler(max_price: int = Query(ge=100, lt=1000, default=100)):
return {"max_price": max_price}
📌 URL에 붙는 ?key=value 형식의 파라미터 처리
- Query()를 사용해 기본값, 최소값(ge), 최대값(lt) 조건 설정
- URL 예시: /api/v1/items?max_price=500
💡 자동 직렬화로 JSON 형태로 응답됩니다.
3️⃣ Request Body 받기 (JSON)
방법 1: BaseModel을 통한 구조화
class ItemCreateRequest(BaseModel):
name: str
price: float
@router.post("/items")
def create_item_handler(body: ItemCreateRequest):
return {"name": body.name, "price": body.price}
- JSON 요청 예:
{
"name": "Notebook",
"price": 129.99
}
- 자동 유효성 검사 + Swagger 문서화에 유리
방법 2: 단일 필드만 Body로 받기
@router.post("")
def create_item_handler(name: str = Body(embed=True)):
return {"received_name": name}
- JSON 요청:
{ "name": "FastAPI" }
- embed=True를 쓰면 JSON key로 감싸서 전달해야 함
4️⃣ 파일 업로드 (Multi-part Form)
@router.post("/{item_id}/images")
def upload_item_image_handler(image: UploadFile):
return {
"filename": image.filename,
"content_type": image.content_type
}
📌 HTML <form enctype="multipart/form-data">로부터 전송되는 파일 처리
- UploadFile을 사용하면 파일 이름, 타입 등에 접근 가능
- Swagger에서 직접 업로드 가능!
5️⃣ FastAPI 앱 설정 및 라우터 등록
app = FastAPI()
app.include_router(item_router)
app.include_router(user_router)
- 라우터 단위로 파일을 분리해서 관리 가능 (모듈화)
6️⃣ 다양한 응답 포맷 제공하기
6-1) HTML 응답
@app.get("/html")
def render_html_handler():
content = f"<html><body><h1> now: {datetime.now()}</h1></body></html>"
return HTMLResponse(content)
- 브라우저에서 HTML로 렌더링됨
6-2) Plain Text 응답
@app.get("/plain-text")
def plain_text_handler():
return Response(content="Hello World!", media_type="text/plain")
- 간단한 텍스트 메시지 전달에 유용
6-3) 파일 다운로드 응답
@app.get("/images")
def image_download_handler():
return FileResponse("images/pystagram.png", headers={"Content-Disposition": "attachment; filename=caleb"})
- 이미지 또는 파일을 다운로드 가능
6-4) BaseModel로 응답 데이터 구조화
class NowResponse(BaseModel):
now: datetime
@app.get("/base-model")
def base_model_response_handler() -> NowResponse:
return NowResponse(now=datetime.now())
- Swagger 문서에 응답 구조 자동 표시됨
✅ 마무리 요약
기능 사용 요소 특징
| Path Parameter | /{item_id} | URL 경로 값 처리 |
| Query Parameter | Query() | 유효성 검사 및 기본값 설정 |
| Request Body | BaseModel 또는 Body() | JSON 기반 데이터 수신 |
| File Upload | UploadFile | 파일 이름, 타입 접근 |
| HTML/Text 응답 | HTMLResponse, Response | 콘텐츠 타입 지정 |
| 파일 다운로드 | FileResponse | 다운로드 처리 |
| 구조화된 응답 | BaseModel 반환 | 명시적 타입 + 문서 자동 생성 |
이처럼 FastAPI는 타입 힌트 기반으로 요청-응답 구조를 명확하게 정의하고, API 문서를 자동 생성해주는 강력한 기능을 제공합니다. 실무에서 자주 쓰이는 패턴이므로 꼭 숙지해두세요 ✅
'특강' 카테고리의 다른 글
| [FastAPI 2일차] 📘 FastAPI 라우팅과 응답 구조 마스터 가이드 2/2 (250528) (0) | 2025.05.28 |
|---|---|
| [FastAPI 2일차] FastAPI에서 타입 힌트(Type Hint)의 목적과 활용법 완전 정리 1/2 (250528) (0) | 2025.05.28 |
| [FastAPI 1일차] FastAPI 튜토리얼: 개념부터 코드까지 한눈에 정리 2/2 (250526) (0) | 2025.05.26 |
| [FastAPI 1일차] FastAPI 튜토리얼: 개념부터 코드까지 한눈에 정리 1/2 (250526) (0) | 2025.05.26 |
| 🚀 FastAPI 입문 가이드: 설치부터 실행까지 한 번에!(1일차) (0) | 2025.05.26 |