FastAPI로 기존 Flask 프로젝트 마이그레이션하기

배경

사내 API 서버가 Flask로 작성되어 있었는데, 문서화가 되어있지 않아 신규 팀원 온보딩이 어려웠다. FastAPI가 타입 힌트 기반으로 자동 문서화를 제공한다는 점에 끌려 마이그레이션을 진행했다.

점진적 마이그레이션 전략

전체를 한번에 바꾸기엔 리스크가 커서 단계적 접근을 택했다.

새로운 엔드포인트는 FastAPI로 작성
레거시 Flask 앱과 ASGI 서버에서 동시 운영
트래픽이 적은 엔드포인트부터 순차 마이그레이션

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

app = FastAPI()

class UserResponse(BaseModel):
    id: int
    email: str
    name: Optional[str]

@app.get("/api/users/{user_id}", response_model=UserResponse)
async def get_user(user_id: int):
    user = await db.fetch_user(user_id)
    return user

장점

자동 문서화: /docs로 Swagger UI가 자동 생성되어 API 스펙 공유가 편해졌다.

타입 안정성: Pydantic 모델 덕분에 요청/응답 검증이 자동화됐다. Flask에서 수동으로 하던 validation 로직이 사라졌다.

성능: uvicorn + async/await로 동시 처리 성능이 체감상 향상됐다. 정확한 벤치마크는 하지 않았지만 응답 시간이 개선됐다.

주의점

기존 Flask 미들웨어나 데코레이터를 그대로 쓸 수 없어서 일부 로직은 재작성이 필요했다. 특히 인증 관련 부분에서 시간이 걸렸다.

ORM은 SQLAlchemy를 그대로 사용했는데, async 지원이 완전하지 않아서 일부 쿼리는 sync 방식으로 유지했다.

결론

아직 완전 마이그레이션은 못했지만, 새 코드는 모두 FastAPI로 작성 중이다. 타입 힌트만 제대로 작성하면 문서화와 검증이 자동으로 되니 개발 속도가 빨라졌다.