Python FastAPI로 REST API 빠르게 만들기

FastAPI의 진짜 장점은 단순한 개발 속도만이 아닙니다. 타입 힌트, 검증, dependency injection을 통해 **API 계약 경계를 코드에 더 명확히 드러낼 수 있다는 점**이 핵심입니다.

문제는 데모 코드가 짧고 예쁘다고 해서, 그 구조가 그대로 운영 서비스까지 견딘다는 뜻은 아니라는 점입니다. 초기에 경계를 분명히 하지 않으면 FastAPI도 금방 라우터 중심의 뒤섞인 코드가 됩니다.

요청 스키마와 응답 스키마를 분리해야 합니다

운영 서비스에서 가장 중요한 습관 중 하나는 외부 API 계약과 내부 모델을 분리하는 것입니다.

보통 다음처럼 나누는 편이 안전합니다.

request schema는 클라이언트 입력을 검증
response schema는 외부에 약속할 응답 형태를 정의
ORM 모델은 내부 구현으로 유지
서비스 내부 객체와 외부 응답을 섞지 않음

하나의 모델을 모든 계층에서 재사용하면, 내부 스키마 변경이 곧 외부 계약 파괴로 이어지기 쉽습니다.

Dependency injection은 경계를 표현해야 합니다

FastAPI의 dependency는 강력하지만, 비즈니스 로직이 숨어드는 통로가 되기도 쉽습니다.

dependency가 특히 잘 맞는 역할은 다음입니다.

인증 사용자 추출
tenant 해석
DB 세션 제공
request 단위 policy 체크
rate limit이나 feature flag 같은 공통 인프라 관심사

반면 비즈니스 판단과 유스케이스 오케스트레이션은 여전히 서비스나 도메인 계층에 남는 편이 좋습니다.

구조는 작아도 책임은 분명해야 합니다

실전 FastAPI 서비스는 보통 다음 정도 구조만으로도 충분히 건강하게 유지됩니다.

router: HTTP 경로와 조합
schema: 요청/응답 계약
service: 유스케이스와 비즈니스 규칙
repository 또는 gateway: 저장소/외부 연동
dependency: 공통 경계 처리

중요한 것은 대형 구조를 만드는 것이 아니라, route handler가 모든 책임을 떠안지 않게 하는 것입니다.

검증은 경계에서 끝내야 합니다

FastAPI는 Pydantic으로 입력 검증을 쉽게 만들 수 있지만, 여전히 다음을 분리해서 생각해야 합니다.

입력 형식 검증
비즈니스 규칙 검증
권한 검증

입력 형식 오류는 API 경계에서, 비즈니스 규칙 오류는 서비스나 도메인에서 다뤄야 오류 모델이 일관되고 테스트도 쉬워집니다.

인증과 인가는 초기에 정책을 정하는 편이 낫습니다

FastAPI 프로젝트는 인증은 금방 붙지만, 인가 모델은 늦게 정해지는 경우가 많습니다.

더 안전한 접근은 다음을 초기에 정하는 것입니다.

인증 상태를 요청 컨텍스트에 어떻게 넣을 것인가
역할 또는 소유권 검사를 어디서 수행할 것인가
401과 403 응답을 어떻게 구분할 것인가
토큰 파싱, 사용자 로딩, policy 체크를 분리할 것인가

이 기준이 없으면 route handler에서 identity, data access, authorization이 뒤섞이기 쉽습니다.

예외 처리도 일관된 정책이 필요합니다

서비스가 커질수록 클라이언트는 framework 기본 오류보다 예측 가능한 오류 구조를 더 필요로 합니다.

좋은 오류 정책은 보통 다음을 포함합니다.

일관된 error response 구조
도메인 오류를 안정적인 HTTP 상태 코드로 매핑
로그에 correlation ID 또는 request ID 남기기
내부 상세는 클라이언트에 숨기되 운영자는 추적 가능하게 유지

이 기준이 없으면 FastAPI 서비스는 쓰기 쉬워도 운영하기는 어려워집니다.

Async는 유용하지만 마법은 아닙니다

FastAPI는 비동기 I/O와 잘 맞지만, async를 곧바로 성능 향상과 동일시하면 위험합니다.

여전히 다음을 이해해야 합니다.

사용하는 라이브러리가 진짜 async인지
어디에 blocking call이 숨어 있는지
worker 수와 concurrency limit이 배포에서 어떻게 동작하는지
느린 downstream이 있을 때 어떤 병목이 생기는지

async 프레임워크라도 내부에서 blocking DB 또는 HTTP 호출이 많으면 부하에서 쉽게 막힙니다.

운영 체크포인트는 초기에 잡는 편이 쌉니다

운영 가능한 FastAPI 서비스라면 최소한 다음에 답할 수 있어야 합니다.

request timeout 정책
payload size 제한
request ID와 latency tracing
health/readiness 동작
의존 서비스 timeout budget
OpenAPI 문서와 실제 계약의 일치 여부

이런 기준은 트래픽이 붙은 뒤보다 초기에 정하는 편이 훨씬 비용이 낮습니다.

흔한 실수

실무에서는 다음 패턴이 자주 문제를 만듭니다.

ORM 객체를 그대로 응답으로 반환
dependency 안에 비즈니스 로직을 넣음
route handler에서 검증, 권한, 비즈니스 규칙을 한 번에 처리
async가 자동으로 처리량을 해결한다고 오해
운영 환경에서도 기본 예외 처리 동작에 의존

FastAPI가 빠르게 데모를 만들 수 있기 때문에 더 자주 생기는 실수들입니다.

마무리

좋은 FastAPI 서비스는 데모처럼 간결하지만, 경계와 운영 기준은 훨씬 더 엄격합니다.

그 기준이 있어야 빠르게 시작한 코드베이스가 기능과 트래픽이 늘어도 유지보수 가능한 상태로 남습니다.

다음으로 읽기 좋은 글

⚙️ Backend

실전에서 버티는 Spring Boot REST API 설계

Spring Boot REST API를 빠르게 만드는 방법이 아니라, 엔드포인트가 늘고 트래픽과 팀 규모가 커져도 경계가 무너지지 않도록 설계하는 기준을 정리합니다.

⚙️ Backend

비동기 작업 API의 멱등성과 상태 제어

긴 작업을 HTTP 요청 하나로 끝내지 않고 작업 생성, 재시도, 취소, 결과 조회까지 안정적으로 설계하는 방법을 정리합니다.

💬 Language

Python Service Layer 패턴 실전 적용

Python 애플리케이션에서 transport, 비즈니스 규칙, persistence 책임을 분리하는 실전 구조를 정리합니다.