FastAPI는 Python으로 고성능 웹 API를 빠르게 개발할 수 있게 해주는 현대적 웹 프레임워크다. Starlette와 Pydantic을 기반으로 하며, 자동 API 문서 생성, 타입 힌팅, 비동기 지원 등 강력한 기능을 제공한다. 이 글은 FastAPI를 활용한 실전 웹 API 개발의 모든 것을 다룬다.
\npip install fastapi uvicorn[standard]# main.py\nfrom fastapi import FastAPI\nfrom fastapi.responses import JSONResponse\n\napp = FastAPI(\n title=\"My API\",\n description=\"FastAPI 완전정복 가이드\",\n version=\"1.0.0\"\n)\n\n@app.get(\"/\")\nasync def root():\n return {\"message\": \"Hello World\"}\n\n@app.get(\"/health\")\nasync def health_check():\n return JSONResponse(\n content={\"status\": \"healthy\"},\n status_code=200\n )\n\n# 서버 실행\n# uvicorn main:app --reloadfrom fastapi import FastAPI, Query, Path\nfrom typing import Optional\nfrom pydantic import BaseModel\n\napp = FastAPI()\n\n# 경로 매개변수\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: int):\n return {\"user_id\": user_id}\n\n# 쿼리 매개변수\n@app.get(\"/items/\")\nasync def read_items(\n skip: int = 0,\n limit: int = Query(10, ge=1, le=100),\n q: Optional[str] = Query(None, min_length=3, max_length=50)\n):\n return {\n \"skip\": skip,\n \"limit\": limit,\n \"q\": q\n }\n\n# 경로와 쿼리 조합\n@app.get(\"/users/{user_id}/items/{item_id}\")\nasync def get_user_item(\n user_id: int = Path(..., gt=0),\n item_id: int = Path(..., gt=0),\n q: Optional[str] = None,\n short: bool = False\n):\n return {\n \"user_id\": user_id,\n \"item_id\": item_id,\n \"q\": q,\n \"short\": short\n }from pydantic import BaseModel, Field, EmailStr, validator\nfrom typing import Optional, List\nfrom datetime import datetime\nfrom enum import Enum\n\nclass UserRole(str, Enum):\n ADMIN = \"admin\"\n USER = \"user\"\n GUEST = \"guest\"\n\nclass UserBase(BaseModel):\n email: EmailStr\n full_name: str = Field(..., min_length=1, max_length=100)\n age: int = Field(..., ge=0, le=120)\n\nclass UserCreate(UserBase):\n password: str = Field(..., min_length=8, max_length=100)\n \n @validator('password')\n def validate_password(cls, v):\n if not any(char.isdigit() for char in v):\n raise ValueError('Password must contain at least one digit')\n if not any(char.isupper() for char in v):\n raise ValueError('Password must contain at least one uppercase letter')\n return v\n\nclass UserResponse(UserBase):\n id: int\n role: UserRole\n created_at: datetime\n is_active: bool\n \n class Config:\n from_attributes = True # Pydantic v2 (이전에는 orm_mode=True)\n\nclass UserUpdate(BaseModel):\n email: Optional[EmailStr] = None\n full_name: Optional[str] = Field(None, min_length=1, max_length=100)\n age: Optional[int] = Field(None, ge=0, le=120)from typing import List, Optional\n\nclass Item(BaseModel):\n name: str\n description: Optional[str] = None\n price: float = Field(..., gt=0)\n tax: Optional[float] = Field(None, ge=0, le=1)\n\nclass OrderCreate(BaseModel):\n user_id: int\n items: List[Item] = Field(..., min_items=1)\n shipping_address: str\n\nclass OrderResponse(BaseModel):\n id: int\n user_id: int\n items: List[Item]\n total: float\n created_at: datetime\n \n class Config:\n from_attributes = Truefrom pydantic import validator, root_validator\nimport re\n\nclass UserRegistration(BaseModel):\n username: str\n email: EmailStr\n password: str\n confirm_password: str\n phone: Optional[str] = None\n \n @validator('username')\n def validate_username(cls, v):\n if not re.match(r'^[a-zA-Z0-9_]{3,20}$', v):\n raise ValueError('Username must be 3-20 alphanumeric characters or underscores')\n return v\n \n @validator('phone')\n def validate_phone(cls, v):\n if v and not re.match(r'^\\+?[1-9]\\d{1,14}$', v):\n raise ValueError('Invalid phone number format')\n return v\n \n @root_validator\n def validate_passwords_match(cls, values):\n password = values.get('password')\n confirm_password = values.get('confirm_password')\n if password != confirm_password:\n raise ValueError('Passwords do not match')\n return valuesfrom fastapi import Depends, FastAPI, HTTPException\nfrom typing import Optional\n\napp = FastAPI()\n\n# 간단한 의존성\ndef get_db():\n db = \"database_connection\"\n try:\n yield db\n finally:\n # 클린업 코드\n print(\"Closing database connection\")\n\n@app.get(\"/items/\")\nasync def read_items(db: str = Depends(get_db)):\n return {\"db\": db}\n\n# 의존성 체인\ndef get_query_token(token: str = Query(...)):\n return token\n\ndef get_token_header(token: str = Depends(get_query_token)):\n if token != \"secret-token\":\n raise HTTPException(status_code=403, detail=\"Invalid token\")\n return token\n\n@app.get(\"/protected/\")\nasync def protected_route(token: str = Depends(get_token_header)):\n return {\"message\": \"Access granted\"}from fastapi import Depends\nfrom typing import Optional\n\nclass PaginationParams:\n def __init__(\n self,\n skip: int = 0,\n limit: int = 10\n ):\n self.skip = skip\n self.limit = limit\n\n@app.get(\"/items/\")\nasync def read_items(pagination: PaginationParams = Depends()):\n return {\n \"skip\": pagination.skip,\n \"limit\": pagination.limit\n }from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom sqlalchemy.orm import sessionmaker\nfrom contextlib import asynccontextmanager\n\n# 데이터베이스 설정\nDATABASE_URL = \"postgresql+asyncpg://user:password@localhost/dbname\"\n\nengine = create_async_engine(DATABASE_URL, echo=True)\nAsyncSessionLocal = sessionmaker(\n engine, class_=AsyncSession, expire_on_commit=False\n)\n\nasync def get_db() -> AsyncSession:\n async with AsyncSessionLocal() as session:\n try:\n yield session\n await session.commit()\n except Exception:\n await session.rollback()\n raise\n finally:\n await session.close()\n\n@app.get(\"/users/\")\nasync def get_users(db: AsyncSession = Depends(get_db)):\n result = await db.execute(select(User))\n users = result.scalars().all()\n return usersimport asyncio\nimport aiohttp\nfrom fastapi import FastAPI\nfrom typing import List\n\napp = FastAPI()\n\nasync def fetch_data(url: str) -> dict:\n async with aiohttp.ClientSession() as session:\n async with session.get(url) as response:\n return await response.json()\n\n@app.get(\"/fetch-multiple/\")\nasync def fetch_multiple_urls(urls: List[str]):\n # 병렬 실행\n tasks = [fetch_data(url) for url in urls]\n results = await asyncio.gather(*tasks)\n return results\n\n# 타임아웃 처리\nasync def fetch_with_timeout(url: str, timeout: int = 5):\n try:\n return await asyncio.wait_for(fetch_data(url), timeout=timeout)\n except asyncio.TimeoutError:\n return {\"error\": \"Request timeout\"}from fastapi import BackgroundTasks\nfrom fastapi import FastAPI\n\napp = FastAPI()\n\ndef send_email(email: str, message: str):\n # 이메일 전송 로직\n print(f\"Sending email to {email}: {message}\")\n\ndef log_activity(user_id: int, action: str):\n # 활동 로깅\n print(f\"User {user_id} performed {action}\")\n\n@app.post(\"/users/\", response_model=UserResponse)\nasync def create_user(\n user: UserCreate,\n background_tasks: BackgroundTasks,\n db: AsyncSession = Depends(get_db)\n):\n # 사용자 생성\n db_user = User(**user.dict())\n db.add(db_user)\n await db.commit()\n await db.refresh(db_user)\n \n # 백그라운드 작업 추가\n background_tasks.add_task(send_email, user.email, \"Welcome!\")\n background_tasks.add_task(log_activity, db_user.id, \"user_created\")\n \n return db_userfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n # 시작 시 실행\n print(\"Starting up...\")\n # 초기화 작업 (DB 연결, 캐시 설정 등)\n yield\n # 종료 시 실행\n print(\"Shutting down...\")\n # 클린업 작업\n\napp = FastAPI(lifespan=lifespan)from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.orm import sessionmaker\nfrom sqlalchemy import Column, Integer, String, DateTime, Boolean\nfrom datetime import datetime\n\nBase = declarative_base()\n\nclass User(Base):\n __tablename__ = \"users\"\n \n id = Column(Integer, primary_key=True, index=True)\n email = Column(String, unique=True, index=True, nullable=False)\n full_name = Column(String, nullable=False)\n hashed_password = Column(String, nullable=False)\n is_active = Column(Boolean, default=True)\n created_at = Column(DateTime, default=datetime.utcnow)\n\n# 엔진과 세션 생성\nDATABASE_URL = \"postgresql+asyncpg://user:password@localhost/dbname\"\n\nengine = create_async_engine(\n DATABASE_URL,\n echo=True,\n future=True\n)\n\nAsyncSessionLocal = sessionmaker(\n engine,\n class_=AsyncSession,\n expire_on_commit=False\n)\n\n# 테이블 생성\nasync def init_db():\n async with engine.begin() as conn:\n await conn.run_sync(Base.metadata.create_all)from sqlalchemy import select, update, delete\nfrom sqlalchemy.ext.asyncio import AsyncSession\nfrom typing import List, Optional\n\nclass UserRepository:\n def __init__(self, db: AsyncSession):\n self.db = db\n \n async def create(self, user_data: UserCreate) -> User:\n hashed_password = get_password_hash(user_data.password)\n db_user = User(\n email=user_data.email,\n full_name=user_data.full_name,\n hashed_password=hashed_password\n )\n self.db.add(db_user)\n await self.db.commit()\n await self.db.refresh(db_user)\n return db_user\n \n async def get_by_id(self, user_id: int) -> Optional[User]:\n result = await self.db.execute(\n select(User).where(User.id == user_id)\n )\n return result.scalar_one_or_none()\n \n async def get_by_email(self, email: str) -> Optional[User]:\n result = await self.db.execute(\n select(User).where(User.email == email)\n )\n return result.scalar_one_or_none()\n \n async def get_all(\n self,\n skip: int = 0,\n limit: int = 100\n ) -> List[User]:\n result = await self.db.execute(\n select(User)\n .offset(skip)\n .limit(limit)\n )\n return result.scalars().all()\n \n async def update(\n self,\n user_id: int,\n user_update: UserUpdate\n ) -> Optional[User]:\n update_data = user_update.dict(exclude_unset=True)\n if not update_data:\n return await self.get_by_id(user_id)\n \n await self.db.execute(\n update(User)\n .where(User.id == user_id)\n .values(**update_data)\n )\n await self.db.commit()\n return await self.get_by_id(user_id)\n \n async def delete(self, user_id: int) -> bool:\n result = await self.db.execute(\n delete(User).where(User.id == user_id)\n )\n await self.db.commit()\n return result.rowcount > 0\n\n# API 엔드포인트\n@app.post(\"/users/\", response_model=UserResponse, status_code=201)\nasync def create_user(\n user: UserCreate,\n db: AsyncSession = Depends(get_db)\n):\n repository = UserRepository(db)\n \n # 이메일 중복 확인\n existing_user = await repository.get_by_email(user.email)\n if existing_user:\n raise HTTPException(\n status_code=400,\n detail=\"Email already registered\"\n )\n \n return await repository.create(user)\n\n@app.get(\"/users/{user_id}\", response_model=UserResponse)\nasync def get_user(\n user_id: int,\n db: AsyncSession = Depends(get_db)\n):\n repository = UserRepository(db)\n user = await repository.get_by_id(user_id)\n if not user:\n raise HTTPException(status_code=404, detail=\"User not found\")\n return userfrom datetime import datetime, timedelta\nfrom typing import Optional\nfrom jose import JWTError, jwt\nfrom passlib.context import CryptContext\nfrom fastapi import Depends, HTTPException, status\nfrom fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm\n\n# 설정\nSECRET_KEY = \"your-secret-key\"\nALGORITHM = \"HS256\"\nACCESS_TOKEN_EXPIRE_MINUTES = 30\n\npwd_context = CryptContext(schemes=[\"bcrypt\"], deprecated=\"auto\")\noauth2_scheme = OAuth2PasswordBearer(tokenUrl=\"token\")\n\ndef verify_password(plain_password: str, hashed_password: str) -> bool:\n return pwd_context.verify(plain_password, hashed_password)\n\ndef get_password_hash(password: str) -> str:\n return pwd_context.hash(password)\n\ndef create_access_token(data: dict, expires_delta: Optional[timedelta] = None):\n to_encode = data.copy()\n if expires_delta:\n expire = datetime.utcnow() + expires_delta\n else:\n expire = datetime.utcnow() + timedelta(minutes=15)\n to_encode.update({\"exp\": expire})\n encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)\n return encoded_jwt\n\nasync def get_current_user(\n token: str = Depends(oauth2_scheme),\n db: AsyncSession = Depends(get_db)\n) -> User:\n credentials_exception = HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Could not validate credentials\",\n headers={\"WWW-Authenticate\": \"Bearer\"},\n )\n try:\n payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])\n user_id: int = payload.get(\"sub\")\n if user_id is None:\n raise credentials_exception\n except JWTError:\n raise credentials_exception\n \n repository = UserRepository(db)\n user = await repository.get_by_id(user_id)\n if user is None:\n raise credentials_exception\n return user\n\n@app.post(\"/token\")\nasync def login(\n form_data: OAuth2PasswordRequestForm = Depends(),\n db: AsyncSession = Depends(get_db)\n):\n repository = UserRepository(db)\n user = await repository.get_by_email(form_data.username)\n if not user or not verify_password(form_data.password, user.hashed_password):\n raise HTTPException(\n status_code=status.HTTP_401_UNAUTHORIZED,\n detail=\"Incorrect username or password\",\n headers={\"WWW-Authenticate\": \"Bearer\"},\n )\n access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)\n access_token = create_access_token(\n data={\"sub\": user.id}, expires_delta=access_token_expires\n )\n return {\"access_token\": access_token, \"token_type\": \"bearer\"}\n\n@app.get(\"/users/me/\", response_model=UserResponse)\nasync def read_users_me(current_user: User = Depends(get_current_user)):\n return current_userfrom enum import Enum\nfrom fastapi import Depends, HTTPException, status\n\nclass Role(str, Enum):\n ADMIN = \"admin\"\n USER = \"user\"\n GUEST = \"guest\"\n\ndef require_role(required_role: Role):\n async def role_checker(current_user: User = Depends(get_current_user)):\n if current_user.role != required_role:\n raise HTTPException(\n status_code=status.HTTP_403_FORBIDDEN,\n detail=\"Not enough permissions\"\n )\n return current_user\n return role_checker\n\n@app.delete(\"/users/{user_id}\")\nasync def delete_user(\n user_id: int,\n current_user: User = Depends(require_role(Role.ADMIN)),\n db: AsyncSession = Depends(get_db)\n):\n repository = UserRepository(db)\n success = await repository.delete(user_id)\n if not success:\n raise HTTPException(status_code=404, detail=\"User not found\")\n return {\"message\": \"User deleted\"}from fastapi import WebSocket, WebSocketDisconnect\nfrom typing import List\n\nclass ConnectionManager:\n def __init__(self):\n self.active_connections: List[WebSocket] = []\n \n async def connect(self, websocket: WebSocket):\n await websocket.accept()\n self.active_connections.append(websocket)\n \n def disconnect(self, websocket: WebSocket):\n self.active_connections.remove(websocket)\n \n async def send_personal_message(self, message: str, websocket: WebSocket):\n await websocket.send_text(message)\n \n async def broadcast(self, message: str):\n for connection in self.active_connections:\n await connection.send_text(message)\n\nmanager = ConnectionManager()\n\n@app.websocket(\"/ws/{client_id}\")\nasync def websocket_endpoint(websocket: WebSocket, client_id: int):\n await manager.connect(websocket)\n try:\n while True:\n data = await websocket.receive_text()\n await manager.send_personal_message(\n f\"Message text was: {data}\", websocket\n )\n await manager.broadcast(f\"Client #{client_id} says: {data}\")\n except WebSocketDisconnect:\n manager.disconnect(websocket)\n await manager.broadcast(f\"Client #{client_id} left the chat\")from typing import Dict\nimport json\n\nclass ChatManager:\n def __init__(self):\n self.rooms: Dict[str, List[WebSocket]] = {}\n \n async def connect(self, websocket: WebSocket, room: str):\n await websocket.accept()\n if room not in self.rooms:\n self.rooms[room] = []\n self.rooms[room].append(websocket)\n \n def disconnect(self, websocket: WebSocket, room: str):\n if room in self.rooms:\n self.rooms[room].remove(websocket)\n \n async def send_message(self, message: dict, room: str):\n if room in self.rooms:\n for connection in self.rooms[room]:\n await connection.send_json(message)\n\nchat_manager = ChatManager()\n\n@app.websocket(\"/ws/chat/{room}\")\nasync def chat_endpoint(websocket: WebSocket, room: str):\n await chat_manager.connect(websocket, room)\n try:\n while True:\n data = await websocket.receive_text()\n message = json.loads(data)\n await chat_manager.send_message(message, room)\n except WebSocketDisconnect:\n chat_manager.disconnect(websocket, room)from fastapi import UploadFile, File\nfrom fastapi.responses import FileResponse\nimport aiofiles\nimport os\n\nUPLOAD_DIR = \"uploads\"\nos.makedirs(UPLOAD_DIR, exist_ok=True)\n\n@app.post(\"/upload/\")\nasync def upload_file(file: UploadFile = File(...)):\n file_path = os.path.join(UPLOAD_DIR, file.filename)\n \n async with aiofiles.open(file_path, 'wb') as f:\n content = await file.read()\n await f.write(content)\n \n return {\n \"filename\": file.filename,\n \"content_type\": file.content_type,\n \"size\": len(content)\n }\n\n@app.get(\"/download/{filename}\")\nasync def download_file(filename: str):\n file_path = os.path.join(UPLOAD_DIR, filename)\n if os.path.exists(file_path):\n return FileResponse(\n file_path,\n media_type='application/octet-stream',\n filename=filename\n )\n raise HTTPException(status_code=404, detail=\"File not found\")from typing import List\n\n@app.post(\"/upload-multiple/\")\nasync def upload_multiple_files(files: List[UploadFile] = File(...)):\n uploaded_files = []\n \n for file in files:\n file_path = os.path.join(UPLOAD_DIR, file.filename)\n async with aiofiles.open(file_path, 'wb') as f:\n content = await file.read()\n await f.write(content)\n \n uploaded_files.append({\n \"filename\": file.filename,\n \"size\": len(content)\n })\n \n return {\"uploaded_files\": uploaded_files}from fastapi import FastAPI, Request, status\nfrom fastapi.responses import JSONResponse\nfrom fastapi.exceptions import RequestValidationError\nfrom starlette.exceptions import HTTPException as StarletteHTTPException\n\napp = FastAPI()\n\nclass CustomException(Exception):\n def __init__(self, message: str, status_code: int = 400):\n self.message = message\n self.status_code = status_code\n\n@app.exception_handler(CustomException)\nasync def custom_exception_handler(request: Request, exc: CustomException):\n return JSONResponse(\n status_code=exc.status_code,\n content={\"detail\": exc.message}\n )\n\n@app.exception_handler(StarletteHTTPException)\nasync def http_exception_handler(request: Request, exc: StarletteHTTPException):\n return JSONResponse(\n status_code=exc.status_code,\n content={\"detail\": exc.detail}\n )\n\n@app.exception_handler(RequestValidationError)\nasync def validation_exception_handler(request: Request, exc: RequestValidationError):\n return JSONResponse(\n status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,\n content={\"detail\": exc.errors()}\n )from fastapi import Request\nfrom starlette.middleware.base import BaseHTTPMiddleware\nimport time\n\nclass TimingMiddleware(BaseHTTPMiddleware):\n async def dispatch(self, request: Request, call_next):\n start_time = time.time()\n response = await call_next(request)\n process_time = time.time() - start_time\n response.headers[\"X-Process-Time\"] = str(process_time)\n return response\n\nclass LoggingMiddleware(BaseHTTPMiddleware):\n async def dispatch(self, request: Request, call_next):\n print(f\"Request: {request.method} {request.url}\")\n response = await call_next(request)\n print(f\"Response: {response.status_code}\")\n return response\n\napp.add_middleware(TimingMiddleware)\napp.add_middleware(LoggingMiddleware)# test_main.py\nfrom fastapi.testclient import TestClient\nfrom main import app\n\nclient = TestClient(app)\n\ndef test_root():\n response = client.get(\"/\")\n assert response.status_code == 200\n assert response.json() == {\"message\": \"Hello World\"}\n\ndef test_create_user():\n response = client.post(\n \"/users/\",\n json={\n \"email\": \"test@example.com\",\n \"full_name\": \"Test User\",\n \"age\": 25,\n \"password\": \"Test1234\"\n }\n )\n assert response.status_code == 201\n data = response.json()\n assert data[\"email\"] == \"test@example.com\"import pytest\nfrom httpx import AsyncClient\nfrom main import app\n\n@pytest.mark.asyncio\nasync def test_async_endpoint():\n async with AsyncClient(app=app, base_url=\"http://test\") as ac:\n response = await ac.get(\"/users/\")\n assert response.status_code == 200# gunicorn_config.py\nbind = \"0.0.0.0:8000\"\nworkers = 4\nworker_class = \"uvicorn.workers.UvicornWorker\"\ntimeout = 120\nkeepalive = 5\n\n# 실행\ngunicorn main:app -c gunicorn_config.py# Dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\n\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\n\nCOPY . .\n\nCMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]FastAPI는 현대적이고 고성능인 Python 웹 프레임워크다. 이 글에서 다룬 내용:
\n이러한 기능들을 조합하면 확장 가능하고 유지보수하기 쉬운 API를 빠르게 개발할 수 있다.
\nFastAPI 완전정복 - 고성능 비동기 웹 API 개발 실전 가이드
\n