🚀 FastAPI 입문 가이드: 설치부터 실행까지 한 번에!

✅ 0. 개발 환경 준비

FastAPI 프로젝트를 시작하기 위한 가장 기초적인 단계입니다.

python3.13 -m venv .fastapi      # 가상환경 생성
source .fastapi/bin/activate     # 가상환경 활성화
pip install "fastapi[standard]"  # FastAPI + Uvicorn 등 필수 패키지 설치

fastapi[standard]는 uvicorn, httpx, pydantic, jinja2 등 개발에 필요한 전체 구성 포함
.fastapi 폴더는 가상환경 디렉토리입니다

📁 main.py 생성하기

FastAPI 앱을 정의할 핵심 파일입니다.

touch main.py

✅ 서버 실행 방법

fastapi dev (fastapi-cli 설치 시 사용 가능)

fastapi dev

공식 실행 방식 (uvicorn)

uvicorn main:app --reload

--reload: 코드 변경 시 서버 자동 재시작 (개발 환경 전용)

🔎 API 테스트 방법: /docs 자동 문서 활용

브라우저 접속: http://127.0.0.1:8000/docs
Swagger UI 제공 → 직접 버튼 클릭으로 요청 실행 가능
별도로 Postman이 없어도 테스트 가능

📌 API 예제 코드 정리

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

1️⃣ Path Parameter 예제

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

/items/100 → item_id = 100으로 받음

2️⃣ Query Parameter 예제

@app.get("/items")
def get_items_handler(max_price: int = 0, category: str = ""):
    if category:
        return {"message": {"category": category, "max_price": max_price}}
    return {"message": {"max_price": max_price}}

/items?max_price=1000&category=food 형태로 요청
max_price, category는 선택적 값으로 처리 가능

3️⃣ Request Body (Pydantic 사용)

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

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

POST 요청 시 JSON 데이터 전송

{
  "name": "Laptop",
  "price": 1999.99
}

자동으로 ItemCreateRequest 모델에 매핑되고 검증됨

✅ 핵심 개념 요약

개념 설명

Path Parameter	URL 경로에 포함된 값 (예: /items/1)
Query Parameter	URL 뒤에 붙는 조건 값 (예: ?category=food)
Request Body	POST 요청 시 JSON 형태로 전달되는 본문 데이터
Pydantic	데이터 검증 + 자동 변환을 처리하는 모델링 도구
/docs	FastAPI가 자동으로 제공하는 Swagger 테스트 UI

🧠 실전 팁

개발 초기엔 uvicorn main:app --reload 로 빠르게 시작
모든 요청은 자동 타입 검증됨 ("20"도 int로 자동 변환)
오류 발생 시 422 응답으로 에러 메시지를 친절하게 반환

✅ 마무리 한 줄 요약

FastAPI는 main.py 하나로도 강력한 API 서버를 만들 수 있으며, Pydantic과 /docs 덕분에 검증과 테스트도 자동화됩니다!