특강

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

Chansman 2025. 5. 26. 20:52

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 개발에 보다 효율적으로 접근할 수 있습니다 ✨