멕시코 결제 플랫폼을 FastAPI로 구축한 엔지니어가 10회 이상 프로덕션 배포를 거치며 발견한 6가지 실전 교훈 공유

Context

결제 처리 시스템에서 웹훅을 단순히 상태 업데이트에만 사용하면 중복 웹훅과 타임존 경계에서 데이터 불일치가 발생한다. Alembic 마이그레이션을 startup 단계에서 실행하면 ECS 헬스 체크가 완료 전에 컨테이너를 종료해 무한 재시작 루프에 빠진다. psycopg2 LIKE 쿼리에서 % 이스케이핑을 잘못하면 검색 엔드포인트가 결과를 반환하지 않는다. 외부 PSP가 VARCHAR로 저장한 타임스탬프는 매번 CAST 연산을 요구해 쿼리 복잡도를 높인다. 인증 엔드포인트는 첫 달부터 브루트포스 공격을 받는다. 데이터베이스 연결 풀 부족으로 KYC 서비스가 부하 시 5xx 에러를 반복 발생시킨다.

Technical Solution

• 웹훅 상태 머신 도입: pending → processing → completed/failed의 정의된 상태 전이 구조로 중복 웹훅과 순서 보장 문제 해결
• ECS 태스크 분리 실행: Alembic 마이그레이션을 애플리케이션 배포 전에 별도 ECS 태스크로 실행해 헬스 체크 타임아웃 방지
• psycopg2 쿼리 패턴 개선: LIKE 쿼리에서 f"%{search}%" 형식의 파이썬 문자열 포매팅 사용으로 이스케이핑 자동화
• Repository → Service → Endpoint 3계층 아키텍처 도입: FastAPI의 Depends()를 통한 의존성 주입으로 각 계층을 독립적으로 테스트 가능하게 구성
• Redis 기반 레이트 리미팅: SlowAPI를 사용해 로그인 5회/분, 일반 엔드포인트 20회/분 제한으로 브루트포스 공격 대응
• 데이터베이스 연결 풀 확대: 풀 크기를 10에서 50으로 증가시켜 고부하 상황의 5xx 에러 제거

Impact

데이터베이스 연결 풀 확대로 KYC 서비스의 5xx 에러가 제거되었다.

Key Takeaway

결제 처리 같은 중요 시스템에서는 웹훅 상태 머신, 마이그레이션 분리 실행, 레이트 리미팅이 필수 요소다. 외부 시스템과의 통합 시 타입 불일치(VARCHAR 타임스탐프 등)와 중복 메시지는 처음부터 방어 로직으로 대응해야 한다.