FastAPI로 RESTful API 서버 구축하며 배운 점

배경

코로나로 재택근무가 시작되면서 사내 워크플로우 자동화 도구가 필요해졌다. 기존에 Flask로 작은 API들을 만들어왔지만, 이번에는 FastAPI를 선택했다. 타입 힌팅 기반의 자동 문서화와 Pydantic을 통한 validation이 매력적으로 보였다.

기본 구조

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional

app = FastAPI()

class TaskRequest(BaseModel):
    title: str
    description: Optional[str] = None
    priority: int = 1

@app.post("/tasks")
async def create_task(task: TaskRequest):
    # 비즈니스 로직
    return {"id": 123, **task.dict()}

Pydantic 모델로 요청 바디를 정의하면 자동으로 validation과 OpenAPI 스펙 생성이 된다. /docs로 접속하면 Swagger UI가 바로 보인다.

Flask 대비 장점

타입 안정성: 함수 시그니처만으로 입출력 스펙이 명확해진다. IDE 자동완성도 잘 작동한다.

비동기 지원: async/await를 네이티브로 지원해서 DB 쿼리나 외부 API 호출 시 성능 개선이 있었다.

import httpx

@app.get("/external-data")
async def fetch_data():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()

자동 문서화: 별도 작업 없이 OpenAPI 문서가 생성된다. 프론트 팀과 협업할 때 /docs 링크만 공유하면 됐다.

주의할 점

동기 라이브러리(psycopg2 등)를 async 함수에서 직접 호출하면 블로킹이 발생한다. asyncpg나 databases 같은 비동기 드라이버를 사용하거나, 동기 코드는 run_in_executor로 감싸야 한다.

결론

2주간 FastAPI로 5개의 엔드포인트를 구현했고, 문서화와 validation 코드를 별도로 작성할 필요가 없어 개발 속도가 빨랐다. Python 3.6+ 타입 힌팅에 익숙하다면 Flask보다 생산성이 높다고 느꼈다. 다음에는 SQLAlchemy와 Alembic을 붙여서 좀 더 복잡한 API를 만들어볼 예정이다.