[TIL] Flask 프로젝트를 FastAPI로 이관하기(1)

Welcome back

꽤 긴 시간동안 포스트를 하지 못했다. 이런 저런 이유가 있겠지만 가장 큰 이유 2가지는 업무와 건강상의 이유로 공백이 꽤나 길어졌다.
지난 몇년간 업무상으로 익힌 여러 스킬들이 있고, 예전의 포스팅들을 보며 "내 과거가 이랬었구나. 지금이랑은 많이 다르구나"를 많이 느끼고, 개발이라는 업무 환경만 놓고 보더라도 참 많이 변했음을 느낀다.
그동안 서비스 회사에서 ASP.NET Core, Python 등으로 백엔드 업무를 진행했고, 간간히 요청이 오면 프론트 작업까지 병행하기도 했다. 이후 여러가지 많은 일들이 있었지만 다시 마음을 다잡고 미래의 내가 지금의 나를 다시 돌아볼 수 있는 포스팅을 다시 이어가고자 한다.

최근에는 지인이 개발 요청을 준 사항이 있어서 간단한 프로젝트를 진행중이다. 특정 도메인을 언급할 순 없지만 AI와 협업하는 AI-Human coWorking 시스템을 개발했고 지속적으로 고도화 중이다.

초반 구축 과정에선 간단한 구현만 진행하는 것으로 설계하여 Flask 프레임워크를 채택하여 문서/일정/WBS/멤버 관리 등 일반적인 업무에 사용하는 내용만 생각했는데, 해당 내용들을 완성하고 보니 AI Agent를 통해서 기획 문서를 공유하고 AI Agent가 일부 페어 프로그래밍을 진행할 수 있을만한 포인트를 확인하여 최근 AI 서비스에서 많이 채택하는 FastAPI로 전체 서비스 이관을 진행할 예정이다.

현재 구조 정리

1. 현재 앱의 성격

이 프로젝트는 처음에는 Flask 기반의 개인 서비스 개발 프로젝트로 시작했다.
문서, 에셋, WBS, 일정, 멤버 관리 기능이 한 애플리케이션 안에 모여 있으며, 최근에는 Cloudflare D1/R2 이관과 React 프론트 전환이 함께 진행되었다.

"왜 CloudFlare를 사용했는가?"라고 궁금증이 생길 수 있다. 물론 GCP나 AWS 등의 서비스도 검토 대상에 두었지만, 현재 상용화 서비스가 아닌 서비스 구현을 위한 실험적인 단계이기 때문에 인프라 비용이 발생하지 않는 CloudFlare와 Pythonanywhere을 채택했다.

현재 구조는 크게 세 축으로 볼 수 있다.

• app/
  • 기존 Flask 서버
• frontend/
  • React 기반 프론트엔드
• worker-python/
  • Cloudflare Python Worker 실험/이행용 서버 코드

2. Flask 서버의 현재 역할

현재 Flask 서버는 아래 역할을 동시에 맡고 있다.

• JSON API 제공
• React 빌드 결과 정적 서빙
• 로컬 업로드 파일 서빙
• SQLite 초기화와 seed 명령 제공
• D1/R2를 포함한 하이브리드 런타임 설정 관리

즉, 전통적인 서버 역할과 임시 운영 보조 기능이 한곳에 모여 있다.

3. 구조적으로 좋은 점

• repository/provider 패턴이 이미 존재한다.
• SQLite와 D1을 추상화하려는 시도가 들어가 있다.
• 스토리지도 local/R2를 분기할 수 있게 되어 있다.
• React 프론트가 분리되어 있어 API 서버 교체가 상대적으로 쉬운 편이다.

이 점들은 FastAPI 마이그레이션에 매우 유리하다.

4. 현재 구조의 제약

4-1. Flask app context 의존

다음 요소들이 Flask 내부 전역 컨텍스트에 기대고 있다.

• current_app
• g
• Blueprint
• jsonify
• send_from_directory
• send_file

이 의존성은 프레임워크 전환 시 가장 먼저 정리해야 하는 대상이다.

4-2. 실행 환경 결합도

현재 서버는 아래를 한 앱에서 직접 처리한다.

• 로컬 SQLite 파일
• instance/ 기반 로그 파일
• uploads/ 기반 파일 서빙
• Cloudflare D1/R2 설정

이 자체가 문제는 아니지만, 범용 배포를 목표로 할 때는 실행환경 의존을 좀 더 드러내고 분리해야 한다.

4-3. Worker 실험 코드와 본 서버 코드의 분리

worker-python/은 FastAPI 기반이지만 Cloudflare Worker 런타임을 전제로 한다.
즉, FastAPI 경험은 이미 일부 축적되어 있지만, 그 코드가 곧바로 “범용 서버”를 의미하지는 않는다.

5. 현재 구조를 한 문장으로 요약하면

Flask 중심의 실서비스 서버와 Cloudflare 전환 실험 코드가 공존하고 있으며, 핵심 도메인 로직은 꽤 재사용 가능하지만 프레임워크/런타임 결합을 더 느슨하게 만들어야 한다.

---

FastAPI 전환 의도

1. 왜 지금 Flask에서 FastAPI로 옮기려고 하는가

이번 전환의 목적은 “Flask가 나쁘다”가 아니다.
핵심은 이 서비스가 특정 런타임이나 호스팅 환경에 잠기지 않게 만드는 것이다.

현재 운영 리스크와 방향성은 아래처럼 정리된다.

• PythonAnywhere 서비스 불안정성 이슈가 발생했다.
• Cloudflare Worker는 매력적이지만, 장기적으로는 Cloudflare 전용 코드 비중이 커질 수 있다.
• 로컬 개발, 다른 클라우드, 확장성을 모두 고려하면 범용 ASGI 앱이 더 적합하다.
• 또한 LLM을 적용 등 AI 개발 방법론을 채택하기엔 Flask보단 FastAPI가 적합하다는 생각을 했다.

2. FastAPI가 이번 상황에 맞는 이유

• ASGI 표준 기반이라 이식성이 좋다.
• 로컬, VPS, Docker, Render, Fly.io, Railway, ECS 등 다양한 환경으로 옮기기 쉽다.
• JSON API 중심 앱에 잘 맞는다.
• 타입 힌트와 문서화 측면에서 사용성이 높다.
• 이미 프로젝트 내부에 FastAPI 경험(worker-python/)이 일부 있다.
• AI 기능을 도입할 부분이 있다.

3. 이번 마이그레이션의 진짜 목표

3-1. 기술 목표

• Flask app context 의존 제거
• 범용 FastAPI 앱 코어 확보
• 저장소/스토리지/설정 계층의 프레임워크 독립성 강화
• JSON API 우선 이전

3-2. 운영 목표

• 로컬 실행 경로 단순화
• 특정 호스팅 벤더 의존도 완화
• 추후 Docker 기반 배포도 가능한 구조 확보

3-3. 목표

• “기능 구현”만이 아니라 “서비스 구조 재설계” 경험을 남긴다.
• 레거시 Flask 앱을 분석하고 ASGI 구조로 이행한 과정을 정리한다.
• 단순 CRUD가 아니라 저장소 추상화, 스토리지 전략, 런타임 이식성 문제를 함께 설명한다.

4. 무엇을 하지 않으려는가

• Cloudflare Worker 전용 구조를 메인 아키텍처로 삼지 않는다.
• 프레임워크 이름만 바꾸는 기계적 치환은 하지 않는다.
• 한 번에 모든 코드를 뒤엎는 빅뱅 전환은 피한다.

5. 전환 전략 한 줄 요약

기존 Flask 앱 옆에 범용 FastAPI 앱을 세우고, 공통 기반을 분리한 뒤 API부터 단계적으로 이전한다.