🚀 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 덕분에 검증과 테스트도 자동화됩니다!