레거시 시스템 현대화 — 10년 된 PHP를 FastAPI로 전환한 이야기

안녕하세요, 코드픽 기술 블로그 독자 여러분!

오랜 시간 서비스를 운영해오신 분들이라면 한 번쯤은 "레거시 시스템"이라는 단어를 듣고 한숨을 쉬어본 경험이 있으실 겁니다. 10년 넘게 회사의 핵심 비즈니스를 지탱해온 든든한 버팀목이지만, 동시에 개발팀에게는 한없이 무거운 짐처럼 느껴지는 존재죠. 낡은 기술 스택, 복잡하게 얽힌 코드, 느린 성능, 신규 기능 개발의 어려움… 이 모든 것이 레거시 시스템이 가진 그림자입니다.

저희 코드픽도 비슷한 상황에 직면했었습니다. 무려 10년 이상 된 PHP 기반의 핵심 백엔드 시스템은 회사의 성장을 이끌었지만, 동시에 미래를 위한 발목을 잡는 듯한 느낌을 주었죠. 더 이상 미룰 수 없다는 판단하에, 저희는 이 레거시 시스템을 최신 기술 스택인 FastAPI 기반으로 현대화하기로 결정했습니다.

이 글에서는 저희가 겪었던 레거시 시스템 현대화 여정, 즉 10년 된 PHP 시스템을 FastAPI로 마이그레이션한 경험을 여러분과 공유하고자 합니다. 왜 이 결정이 필요했는지부터 어떤 전략으로, 어떤 어려움을 겪으며, 어떻게 해결했는지, 그리고 궁극적으로 어떤 이점을 얻었는지까지 솔직하고 실용적인 이야기들을 풀어놓겠습니다. 노후 시스템 현대화를 고민하고 계신 분들에게 저희의 경험이 작은 등불이 되기를 바랍니다.

왜 현대화가 필요했을까요? — 10년 된 PHP 시스템의 한계

저희의 PHP 시스템은 2010년대 초반에 개발되어 약 10년 이상 운영되어 온 서비스였습니다. 당시에는 최신 기술이었지만, 시간이 흐르면서 여러 한계에 부딪히게 되었습니다.

1. 기술 부채와 유지보수의 악몽

가장 큰 문제는 기술 부채였습니다. 오랜 시간 여러 개발자의 손을 거치면서 코드 베이스는 점점 복잡해지고, 일관성 없는 코딩 스타일과 불필요한 중복 로직으로 가득 차게 되었습니다.

• 스파게티 코드: 특정 기능 하나를 수정하려 해도 예상치 못한 사이드 이펙트가 발생하는 경우가 다반사였습니다. 비즈니스 로직이 UI 코드와 뒤섞여 있어 테스트 코드 작성은 엄두도 내지 못했습니다.
• 오래된 라이브러리: 사용하던 PHP 버전과 프레임워크는 이미 공식 지원이 종료되었거나, 보안 취약점이 발견되어도 업데이트하기 어려운 상황이었습니다. 이는 잠재적인 보안 위협으로 이어질 수 있었습니다.
• 개발 생산성 저하: 새로운 기능을 추가하거나 버그를 수정하는 데 드는 시간이 점점 늘어났습니다. 작은 변경에도 전체 시스템을 이해해야 하는 부담 때문에 개발 속도는 현저히 떨어졌습니다.

2. 성능 및 확장성 문제

초기 설계는 트래픽이 많지 않은 상황을 가정했기 때문에, 서비스가 성장하면서 성능 병목 현상이 자주 발생했습니다.

• 느린 응답 속도: 특정 요청에 대한 응답 시간이 길어져 사용자 경험을 저해했습니다. 특히 동시 접속자 수가 늘어나면 서버 부하가 급증하여 서비스가 불안정해지는 경우가 많았습니다.
• 수평 확장 어려움: 시스템 구조 자체가 수평 확장을 고려하지 않았습니다. 서버를 늘려도 성능 개선 효과가 미미하거나, 세션 관리 등의 문제로 복잡도가 크게 증가했습니다.
• 비효율적인 리소스 사용: 불필요한 로직과 비동기 처리가 어려운 구조 탓에 서버 자원(CPU, 메모리)을 비효율적으로 사용했습니다.

3. 개발자 경험 및 인력 수급의 어려움

개발팀 내부적으로도 레거시 시스템은 큰 스트레스 요인이었습니다.

• 낮은 개발 만족도: 낡은 기술 스택과 복잡한 코드베이스는 개발자들의 업무 만족도를 떨어뜨렸습니다. 새로운 기술을 도입하고 혁신적인 아이디어를 시도하기 어려웠습니다.
• 인력 수급 난항: PHP 개발자, 특히 오래된 PHP 프레임워크 경험이 있는 개발자를 찾기 어려웠습니다. 신규 인력이 합류해도 온보딩 기간이 길고, 시스템을 이해하는 데 많은 시간이 소요되었습니다.

이러한 문제들은 단순히 기술적인 어려움을 넘어, 비즈니스 성장의 발목을 잡고 있었습니다. 더 이상 미룰 수 없다는 판단 아래, 저희는 레거시 시스템 현대화라는 큰 도전을 시작하기로 했습니다.

FastAPI, 왜 선택했을까요? — 현대화의 핵심 도구

레거시 시스템 현대화를 결정한 후, 가장 먼저 고민했던 것은 "어떤 기술 스택으로 전환할 것인가?"였습니다. Node.js, Go, Java Spring Boot 등 다양한 선택지가 있었지만, 저희는 최종적으로 Python 기반의 FastAPI를 선택했습니다. 여기에는 몇 가지 분명한 이유가 있었습니다.

1. 압도적인 성능과 비동기 지원

FastAPI는 이름에서 알 수 있듯이 "빠른(Fast)" 성능을 자랑합니다. Python의 비동기 기능을 적극적으로 활용하여 높은 처리량과 낮은 지연 시간을 제공합니다.

• ASGI 기반: Uvicorn, Hypercorn과 같은 ASGI(Asynchronous Server Gateway Interface) 서버 위에서 동작하여, 기존 WSGI 기반의 프레임워크(Django, Flask)보다 훨씬 뛰어난 I/O 성능을 보여줍니다. 데이터베이스, 외부 API 호출 등 I/O 바운드 작업이 많은 백엔드 서비스에 매우 적합합니다.
• Python의 강점: Python은 이미 데이터 과학, 머신러닝, 자동화 등 다양한 분야에서 강력한 생태계를 구축하고 있습니다. 향후 AI 기능 통합이나 데이터 처리 로직 확장에 유리하다는 점도 큰 매력이었습니다.

2. 생산성과 개발자 경험 극대화

FastAPI는 개발자 친화적인 설계 덕분에 개발 생산성을 크게 향상시킵니다.

• Pydantic 기반의 데이터 유효성 검사: Python 타입 힌트를 활용하여 요청(Request) 및 응답(Response) 데이터의 유효성을 자동으로 검사하고 직렬화/역직렬화합니다. 이 덕분에 코드가 간결해지고, 버그 발생 확률이 줄어들며, 개발자는 비즈니스 로직에 집중할 수 있습니다.
• 자동 API 문서 생성 (Swagger/ReDoc): OpenAPI(Swagger) 표준을 준수하여 API 문서를 자동으로 생성해줍니다. 개발팀 내 협업뿐만 아니라 프론트엔드 개발팀, 외부 파트너와의 연동 시에도 큰 도움이 됩니다. API 변경 사항이 즉시 문서에 반영되므로 문서화에 드는 시간과 노력을 절감할 수 있습니다.
• 의존성 주입 (Dependency Injection): 깔끔하고 테스트하기 쉬운 코드 작성을 가능하게 합니다.
• 간결하고 직관적인 문법: Python에 익숙한 개발자라면 빠르게 학습하고 생산성을 낼 수 있습니다.

3. 현대적인 아키텍처와 미래 확장성

FastAPI는 마이크로서비스 아키텍처 구축에 매우 적합합니다.

• 경량성: 필요한 기능만 포함하여 가볍게 서비스를 구축할 수 있습니다.
• 모듈성: 각 서비스를 독립적으로 개발하고 배포할 수 있어 시스템의 유연성과 확장성을 높입니다.
• 활발한 커뮤니티: 빠르게 성장하는 프레임워크인 만큼, 관련 자료와 커뮤니티 지원이 활발하여 문제 해결에 용이합니다.

이러한 이유들로 저희는 FastAPI를 레거시 시스템 현대화의 핵심 기술 스택으로 낙점하고, 본격적인 마이그레이션 준비에 돌입했습니다.

마이그레이션 전략: 점진적 전환 (Strangler Fig Pattern)

10년 된 PHP 시스템을 한 번에 FastAPI로 전환하는 것은 엄청난 위험 부담을 안는 일이었습니다. "빅뱅" 방식의 마이그레이션은 실패할 경우 서비스 전체에 치명적인 영향을 줄 수 있기 때문에, 저희는 "점진적 전환(Strangler Fig Pattern)" 전략을 채택했습니다.

이 전략의 핵심은 기존 시스템을 유지한 채, 새로운 기능을 FastAPI 기반으로 개발하고, 기존 기능 중 중요도가 높거나 변경이 잦은 부분을 점진적으로 FastAPI 서비스로 분리하여 전환하는 것입니다. 마치 무화과나무가 숙주 나무를 서서히 감싸 결국 대체하는 것처럼 말이죠.

구체적인 전략은 다음과 같았습니다.

1. 새로운 기능은 무조건 FastAPI로 개발: 향후 개발될 모든 신규 기능은 FastAPI로 개발하여 기존 PHP 시스템의 비대화를 막습니다.
2. 핵심 비즈니스 로직 분리: 기존 PHP 시스템에서 가장 중요하거나 성능 병목이 심했던 모듈, 혹은 자주 변경되는 모듈부터 FastAPI 기반의 마이크로서비스로 분리합니다.
3. API Gateway / Reverse Proxy 활용: Nginx와 같은 리버스 프록시를 사용하여 특정 URL 패턴에 따라 트래픽을 기존 PHP 서버로 보낼지, 아니면 새로 구축된 FastAPI 서버로 보낼지 결정합니다. 이를 통해 사용자 입장에서는 시스템이 전환되는 것을 인지하지 못하도록 합니다.
4. 데이터베이스 연동: 초기에는 기존 PHP 시스템과 동일한 데이터베이스를 공유하여 데이터 일관성 문제를 최소화했습니다. 점진적으로 데이터베이스 스키마를 개선하거나, 필요한 경우 새로운 데이터베이스를 분리하는 방안도 고려했습니다.
5. 지속적인 모니터링: 전환 과정에서 발생할 수 있는 문제점을 빠르게 감지하고 대응하기 위해 시스템 전체에 대한 철저한 모니터링 환경을 구축했습니다.

이러한 점진적 접근 방식 덕분에 저희는 위험을 최소화하면서 안정적으로 레거시 시스템 현대화를 진행할 수 있었습니다.

핵심 단계별 전환 과정

점진적 전환 전략 아래, 저희는 다음과 같은 단계로 FastAPI 마이그레이션을 진행했습니다.

1단계: 기존 시스템 분석 및 도메인 모델링

가장 먼저 할 일은 기존 PHP 시스템의 비즈니스 로직과 데이터 구조를 완벽하게 이해하는 것이었습니다. 10년 된 시스템은 문서화가 미흡하거나 아예 없는 경우가 많았기에, 기존 코드를 꼼꼼히 분석하고 이해관계자들과의 인터뷰를 통해 숨겨진 로직까지 파악해야 했습니다.

• 코드 리버스 엔지니어링: 기존 PHP 코드를 분석하여 핵심 엔티티, 서비스, 비즈니스 규칙을 파악했습니다.
• 데이터베이스 스키마 분석: 데이터베이스 테이블 구조와 관계를 이해하고, 불필요한 필드나 비효율적인 인덱스 등을 식별했습니다.
• 도메인 모델 설계: 파악된 정보를 바탕으로 새로운 FastAPI 서비스에 적용할 도메인 모델을 Pydantic으로 설계했습니다.

# 예시: 사용자 도메인 모델 (Pydantic)
from pydantic import BaseModel, EmailStr, Field
from datetime import datetime
from typing import Optional

class UserBase(BaseModel):
    email: EmailStr
    username: str = Field(min_length=2, max_length=50)

class UserCreate(UserBase):
    password: str = Field(min_length=8)

class UserInDB(UserBase):
    id: int
    hashed_password: str
    is_active: bool = True
    created_at: datetime
    updated_at: datetime

    class Config:
        orm_mode = True # SQLAlchemy 모델과 연동 시 필요

2단계: 개발 환경 구축 및 초기 서비스 구현

FastAPI 프로젝트를 위한 개발 환경을 구축하고, 가장 간단하면서도 핵심적인 기능을 가진 마이크로서비스를 먼저 구현했습니다.

• 프로젝트 구조 설정: Poetry (의존성 관리)와 Docker (컨테이너화)를 사용하여 개발 환경을 표준화했습니다.
• FastAPI 애플리케이션 초기화: main.py 파일을 생성하고 기본적인 라우팅을 설정했습니다.
• 데이터베이스 연동: SQLAlchemy ORM과 Alembic (마이그레이션 도구)을 사용하여 기존 데이터베이스에 연결하고 모델을 정의했습니다. 비동기 드라이버(asyncpg, asyncmy)를 사용하여 FastAPI의 비동기 이점을 극대화했습니다.
• 첫 번째 API 엔드포인트 구현: 사용자 인증, 또는 간단한 데이터 조회 API 등 비교적 독립적인 기능을 가진 엔드포인트를 먼저 구현하여 개발 프로세스를 검증했습니다.

3단계: API 엔드포인트 설계 및 구현

설계된 도메인 모델을 바탕으로 RESTful API 엔드포인트를 하나씩 구현해 나갔습니다.

• Pydantic 모델 활용: 요청 및 응답 데이터를 Pydantic 모델로 정의하여 자동 유효성 검사와 문서화를 활용했습니다.
• 의존성 주입: Depends를 사용하여 데이터베이스 세션 관리, 인증/인가 로직 등을 깔끔하게 처리했습니다.
• 비동기 처리: async/await 문법을 사용하여 I/O 바운드 작업을 효율적으로 처리했습니다.
• 테스트 코드 작성: pytest와 httpx를 사용하여 각 API 엔드포인트에 대한 단위 테스트 및 통합 테스트를 작성하여 안정성을 확보했습니다.

4단계: 데이터 마이그레이션 및 일관성 확보

기존 PHP 시스템과 새로운 FastAPI 시스템이 동일한 데이터베이스를 공유하는 경우가 많았지만, 일부 모듈은 데이터 스키마 변경이 필요했습니다.

• 스키마 변경: Alembic을 사용하여 데이터베이스 스키마 변경 이력을 관리하고, 안전하게 스키마를 업데이트했습니다.
• 데이터 변환 스크립트: 필요한 경우, 기존 데이터를 새로운 스키마에 맞게 변환하는 Python 스크립트를 작성하여 데이터 정합성을 유지했습니다.
• 양방향 동기화 (선택적): 특정 핵심 데이터의 경우, 전환 기간 동안 PHP와 FastAPI 양쪽에서 데이터를 읽고 쓸 수 있도록 양방향 동기화 로직을 구현하여 데이터 일관성을 철저히 관리했습니다.

5단계: 통합 및 테스트

새로 개발된 FastAPI 서비스와 기존 PHP 시스템 간의 연동을 확인하고, 기능 및 성능 테스트를 수행했습니다.

• API 연동 테스트: 기존 PHP 시스템이 새로운 FastAPI 서비스를 호출하도록 변경하고, 연동이 원활한지 확인했습니다.
• 통합 테스트 및 E2E 테스트: 전체 시스템 흐름에 대한 통합 테스트와 사용자 시나리오 기반의 E2E (End-to-End) 테스트를 수행했습니다.
• 성능 테스트: 부하 테스트 도구(JMeter, Locust)를 사용하여 새로운 FastAPI 서비스의 성능을 측정하고, 기존 PHP 시스템과 비교하여 개선 효과를 확인했습니다.

6단계: 배포 및 모니터링

안정적인 서비스 운영을 위해 배포 자동화 및 모니터링 시스템을 구축했습니다.

• CI/CD 파이프라인: GitHub Actions 또는 GitLab CI/CD를 사용하여 코드 변경 시 자동으로 테스트를 실행하고, Docker 이미지를 빌드하여 배포하는 파이프라인을 구축했습니다.
• 컨테이너 오케스트레이션: Docker Swarm 또는 Kubernetes를 사용하여 FastAPI 서비스를 컨테이너 환경에서 안정적으로 배포하고 스케일링할 수 있도록 했습니다.
• 모니터링 및 로깅: Prometheus, Grafana를 사용하여 서비스 지표를 실시간으로 모니터링하고, ELK Stack (Elasticsearch, Logstash, Kibana)을 통해 로그를 수집 및 분석하여 문제 발생 시 신속하게 대응할 수 있도록 했습니다.

마이그레이션 과정에서 직면한 도전과 해결

레거시 시스템 현대화는 결코 쉽지 않은 여정이었습니다. 예상치 못한 수많은 문제에 직면했지만, 저희는 하나씩 해결해나가며 목표를 향해 나아갔습니다.

1. PHP의 "숨겨진" 비즈니스 로직

가장 큰 도전 중 하나는 기존 PHP 시스템의 코드를 분석하는 과정에서 발견되는 "숨겨진" 비즈니스 로직이었습니다. 문서화되지 않았고, 코드만으로는 파악하기 어려운 예외 처리나 특정 상황에서의 특이 동작들이 많았습니다.

• 해결:
  • 도메인 전문가와의 협업: 시스템을 가장 잘 아는 비즈니스 담당자나 오래 근무한 개발자와의 심도 깊은 인터뷰를 통해 숨겨진 로직을 파악했습니다.
  • 점진적 테스트: 기존 PHP 시스템에 대한 특정 시나리오 테스트를 수행하여 실제 동작을 확인하고, 그 결과를 바탕으로 FastAPI 서비스의 로직을 구현했습니다.
  • 로그 분석: 기존 시스템의 운영 로그를 분석하여 특정 기능이 어떤 조건에서 어떻게 동작했는지 역추적했습니다.

2. 데이터 일관성 문제

점진적 마이그레이션 과정에서 기존 PHP 시스템과 새로운 FastAPI 시스템이 동시에 같은 데이터를 사용하게 되면서 데이터 일관성 문제가 발생할 수 있었습니다. 특히 쓰기 작업이 발생하는 경우 더욱 신중해야 했습니다.

• 해결:
  • 엄격한 트랜잭션 관리: 데이터 변경이 발생하는 모든 로직에 대해 트랜잭션을 철저히 적용하여 원자성을 보장했습니다.
  • 단방향 마이그레이션 우선: 특정 모듈을 FastAPI로 완전히 전환하기 전까지는, 데이터 쓰기 작업은 기존 PHP 시스템에서만 이루어지도록 하고, FastAPI는 읽기 전용으로 두는 방식을 사용했습니다.
  • 데이터 동기화 배치 작업: 전환 기간 동안 데이터 불일치가 발생할 경우를 대비하여 주기적으로 데이터를 비교하고 동기화하는 배치 작업을 구현했습니다.

3. 개발팀의 학습 곡선과 저항

새로운 기술 스택으로의 전환은 개발팀에게 새로운 학습을 요구했습니다. 특히 Python과 비동기 프로그래밍에 익숙하지 않은 개발자들에게는 학습 곡선이 존재했습니다.

• 해결:
  • 내부 스터디 및 워크숍: FastAPI, Python 비동기 프로그래밍, Docker 등에 대한 정기적인 내부 스터디와 워크숍을 진행하여 지식 공유를 활성화했습니다.
  • 페어 프로그래밍: 숙련된 개발자와 함께 코드를 작성하며 실질적인 경험을 쌓을 수 있도록 지원했습니다.
  • 명확한 가이드라인 및 문서화: 새로운 시스템의 아키텍처, 코딩 컨벤션, 개발 가이드라인 등을 명확히 문서화하여 온보딩을 돕고 일관성을 유지했습니다.

4. 성능 최적화 및 병목 현상 해결

FastAPI는 기본적으로 빠르지만, 복잡한 비즈니스 로직이나 비효율적인 데이터베이스 쿼리는 여전히 성능 병목을 유발할 수 있었습니다.

• 해결:
  • 프로파일링 도구 활용: py-spy나 cProfile과 같은 프로파일링 도구를 사용하여 코드의 성능 병목 지점을 식별했습니다.
  • 비동기 데이터베이스 드라이버: asyncpg (PostgreSQL), asyncmy (MySQL)와 같은 비동기 데이터베이스 드라이버를 사용하여 I/O 대기 시간을 최소화했습니다.
  • 캐싱 전략 도입: Redis와 같은 인메모리 데이터 저장소를 활용하여 자주 조회되는 데이터를 캐싱하여 데이터베이스 부하를 줄이고 응답 속도를 향상시켰습니다.
  • 데이터베이스 쿼리 최적화: EXPLAIN 명령어를 활용하여 느린 쿼리를 분석하고 인덱스 추가, 쿼리 재작성 등의 최적화를 수행했습니다.

마이그레이션 결과 및 얻은 이점

힘든 여정이었지만, 레거시 시스템 현대화는 저희에게 상상 이상의 긍정적인 변화를 가져다주었습니다.

1. 드라마틱한 성능 향상

가장 눈에 띄는 변화는 단연 성능이었습니다.

• 응답 시간 단축: 핵심 API의 평균 응답 시간이 기존 PHP 대비 최대 70%까지 단축되었습니다.
• 동시 처리량 증가: 동일한 서버 리소스로 처리할 수 있는 동시 요청 수가 3배 이상 증가했습니다.
• 리소스 효율성 증대: 서버 CPU 및 메모리 사용량이 현저히 줄어들어 운영 비용 절감 효과도 얻을 수 있었습니다.

2. 개발 생산성 및 유지보수성 개선

개발팀의 업무 환경이 혁신적으로 개선되었습니다.

• 빠른 기능 개발: Pydantic의 자동 유효성 검사, 자동 문서화 덕분에 새로운 API를 개발하고 테스트하는 시간이 획기적으로 줄었습니다.
• 쉬운 유지보수: 깔끔하게 분리된 마이크로서비스 아키텍처와 타입 힌트를 활용한 명확한 코드 덕분에 버그를 찾고 수정하는 것이 훨씬 쉬워졌습니다.
• 높은 개발 만족도: 개발자들이 최신 기술 스택으로 작업하며 성취감을 느끼고, 새로운 아이디어를 빠르게 구현할 수 있게 되면서 업무 만족도가 크게 향상되었습니다.

3. 높은 확장성과 안정성

미래 성장을 위한 기반이 단단해졌습니다.

• 유연한 확장: 필요에 따라 특정 마이크로서비스만 독립적으로 스케일 아웃할 수 있게 되어, 트래픽 변화에 유연하게 대응할 수 있게 되었습니다.
• 향상된 안정성: 각 서비스가 독립적으로 운영되므로, 특정 서비스의 장애가 전체 시스템에 미치는 영향을 최소화할 수 있습니다.
• 손쉬운 인력 수급: Python 및 FastAPI 개발자는 시장에 풍부하며, 온보딩 기간도 짧아 인력 수급이 훨씬 용이해졌습니다.

아래 표는 마이그레이션 전후의 주요 지표들을 비교한 내용입니다.

FAQ (자주 묻는 질문)

Q1: 왜 굳이 PHP를 버리고 FastAPI를 선택했나요? PHP도 최신 버전은 괜찮지 않나요?

A1: 물론 최신 PHP 버전(PHP 8.x)과 Laravel, Symfony 같은 현대적인 프레임워크는 매우 훌륭하고 강력합니다. 하지만 저희의 경우 10년 이상 된 PHP 5.x 기반의 레거시 시스템이었고, 특정 프레임워크 없이 개발되어 기술 부채가 매우 심각한 상황이었습니다. 이러한 시스템을 최신 PHP로 업그레이드하는 것 자체도 상당한 노력과 위험이 따르는 일이었습니다.

FastAPI를 선택한 주된 이유는 다음과 같습니다:

• 비동기 처리의 강점: 저희 서비스는 I/O 바운드 작업이 많아 비동기 처리가 필수적이었습니다. FastAPI는 Python의 async/await를 통해 이를 매우 효율적으로 지원합니다.