[FastAPI 1일차] FastAPI 튜토리얼: 개념부터 코드까지 한눈에 정리 2/2 (250526)

FastAPI에서 패스 변수, 쿼리 파라미터, 리퀘스트 바디를 처리하는 방법

---

1. 🚀 FastAPI의 API와 쿼리 파라미터 처리

FastAPI는 API를 정의하면 Swagger UI에서 자동으로 문서화되고, 클라이언트는 웹 인터페이스를 통해 API를 직접 테스트할 수 있습니다.

• 경로 매개변수(Path Parameter): URL의 중괄호({})를 사용해 정의하며, 함수 인자에 타입을 명시하여 사용합니다.
• 쿼리 파라미터(Query Parameter): URL 뒤에 ?key=value 형식으로 붙으며, 함수의 매개변수에서 기본값과 타입을 설정해 처리합니다.

1.1 API 추가의 장점

• 자동 문서화 → Swagger UI에서 시각적으로 확인 가능
• Try it out → 실시간 호출 및 결과 확인
• Postman 없이도 테스트 가능
• JWT 같은 인증 방식도 연동 가능
• 문서 개선 시 입력/응답 형식까지 명확하게 표현 가능

1.2 동적 URL 경로 처리

@app.get("/items/{item_id}")
def get_item(item_id: int):
    return {"item_id": item_id}

• 중괄호로 경로에 변수를 삽입하고, 핸들러 함수에서 타입을 지정해 사용할 수 있습니다.
• 숫자형이면 연산 가능 (예: item_id + 100)
• 타입 불일치 시 → 자동으로 에러 메시지 발생

1.3 타입 지정 및 에러 처리

• int, str, float 등으로 함수 인자의 타입을 제한할 수 있으며, 잘못된 입력 시 FastAPI가 자동으로 파싱 오류를 반환합니다.
• 예: abc를 int로 지정된 매개변수에 넣으면 "value is not a valid integer" 오류 발생

1.4 쿼리 파라미터 개념 및 활용

@app.get("/items")
def read_items(max_price: int, category: str | None = None):
    if category:
        return {"max_price": max_price, "category": category}
    return {"max_price": max_price}

• 쿼리 파라미터는 URL의 ?key=value 형식으로 전달
• 필수로 설정하지 않으려면 기본값 None 또는 값을 지정
• 클라이언트가 추가적인 파라미터를 보낼 경우 → 무시되거나 기본값 적용됨

1.5 패스 변수 vs 쿼리 파라미터

항목 패스 변수 쿼리 파라미터

정의 위치	URL 경로	URL ? 뒤
필수 여부	반드시 필요	선택 가능 (기본값 지정 시)
선언 방식	@app.get("/items/{id}")	def func(id: int = 0)
목적	특정 자원 식별	필터, 조건 지정 등

---

1. 🛠️requestbody 처리와 Pydantic 사용법

2.1 Requestbody?

• 주로 POST, PUT, PATCH 요청 시 사용
• JSON 형식의 데이터를 본문(request body)에 담아 전송

2.2 Pydantic이란?

• Python 데이터 유효성 검사 및 변환용 라이브러리
• FastAPI는 내부적으로 Pydantic의 BaseModel을 활용해 요청/응답 데이터를 다룹니다.

2.3 Pydantic 모델 정의 예시

from pydantic import BaseModel
from datetime import date

class UserSignupRequest(BaseModel):
    username: str
    age: int
    date_of_birth: date

• 클래스 변수에 타입 힌트를 명시
• 타입이 일치하지 않으면 자동 에러 발생 (밸리데이션)
• 날짜 형식은 문자열(예: "2000-01-01")도 자동 변환 가능

2.4 FastAPI에서 리퀘스트 바디 처리 예시

@app.post("/items")
def create_item(item: ItemCreateRequest):
    return {"name": item.name, "price": item.price}

• 함수 인자에 BaseModel 상속 모델을 타입으로 지정 → FastAPI는 이를 JSON Body로 인식
• Swagger UI에서 자동으로 JSON 입력 템플릿 제공됨

2.5 자동 타입 변환 및 유효성 검사

• age: int → 문자열로 전달돼도 자동으로 int로 변환 시도
• 불리언 값도 0/1 → False/True로 변환 가능
• 그러나 명확하지 않거나 허용 범위 밖의 값은 에러 발생

2.6 Pydantic vs DRF Serializer

항목 Pydantic DRF Serializer

주요 목적	데이터 유효성 검사 및 구조화	직렬화/역직렬화 + 유효성 검사
타입 힌트 활용	O	제한적
자동 타입 변환	강력함	일부 지원
활용 범위	요청 + 응답 데이터	주로 요청 데이터 (응답은 Response 객체)

---

1. 📆 예제 실행 결과

• GET /items/1 → {"item_id": 1}
• GET /items?max_price=100 → {"max_price": 100}
• GET /items?max_price=100&category=food → {"max_price": 100, "category": "food"}
• POST /items (JSON body: {"name": "아이폰", "price": 1200000}) → 응답 동일

---

1. 📈 요약 정리

• 패스 변수는 URL 경로에 중괄호로 선언하고 함수 인자와 타입을 일치시켜 처리
• 쿼리 파라미터는 함수 인자에 기본값/타입을 지정해 처리 (선택적 전달 가능)
• 리퀘스트 바디는 Pydantic의 BaseModel을 상속한 클래스를 통해 구조 정의 및 유효성 검사 수행
• FastAPI는 Swagger UI에서 API 테스트와 문서화 기능을 기본 제공
• Pydantic은 직렬화/역직렬화 + 타입 검사를 모두 지원하는 핵심 도구

이렇게 정리된 내용을 기반으로 FastAPI를 활용한 API 개발에 보다 효율적으로 접근할 수 있습니다 ✨