FastAPI 의 설계 철학

FastAPI 는 비교적 짧은 시간 안에 Python 웹 프레임워크의 주류로 자리 잡았습니다. 빠른 등장의 배후에는 type hint · Pydantic · async 를 일관된 한 문장으로 엮은 설계가 있습니다.

1. FastAPI 에 대한 이야기

FastAPI 는 Sebastián Ramírez (tiangolo) 가 만든 Python 웹 프레임워크로 2018 년 12 월 첫 공개로 알려져 있습니다. 두 라이브러리 위에 서 있습니다.

기반	역할	출시
Starlette	ASGI 라우팅·미들웨어·테스트 클라이언트	encode 팀, 2018
Pydantic	타입 기반 데이터 검증·직렬화	Samuel Colvin, 2017

FastAPI 는 라우팅·DI·보안·OpenAPI 자동 생성을 더해 "type hint 만으로 검증·문서화가 따라온다" 는 경험을 만듭니다.

2. Type hint 가 곧 스키마

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.post('/items')
def create(item: Item) -> Item:
    return item

런타임에 item: Item 을 보고 요청 body 를 Pydantic 으로 검증합니다. 같은 정보가 OpenAPI 스키마로 노출되고, /docs (Swagger UI) · /redoc 페이지에서 바로 시도할 수 있습니다.

3. Pydantic v1 → v2

Pydantic v2 (2023-06) 는 핵심 검증을 Rust (pydantic-core) 로 재작성하면서 v1 대비 큰 폭의 성능 향상을 발표했습니다. v1 과 v2 의 API 가 일부 다르며 마이그레이션 가이드가 별도 제공됩니다.

class Config 가 v2 에서 model_config 로 바뀌고 일부 데코레이터·메서드가 변경됐습니다. 라이브러리 간 버전 일치를 먼저 확인합니다.

4. Dependency Injection

FastAPI 의 DI 는 함수 시그니처에 Depends(...) 를 적는 것이 전부입니다.

from fastapi import Depends

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get('/users/{id}')
def read(id: int, db = Depends(get_db)):
    return db.query(User).get(id)

의존도 함수도 type hint 로 자기 의존을 선언할 수 있어 합성됩니다. yield 를 통해 setup/teardown 을 한 함수로 묶는 패턴은 컨텍스트 매니저와 비슷합니다.

같은 요청 안에서 동일 의존은 한 번만 평가됩니다 (캐시). side-effect 가 필요한 의존은 의도와 다를 수 있습니다.

5. async 우선

엔드포인트를 async def 로 선언하면 ASGI 이벤트 루프 위에서 동시 처리됩니다. 동기 함수 (def) 도 그대로 받을 수 있는데, 이 경우 FastAPI 가 별도 스레드 풀에서 실행해 이벤트 루프를 막지 않습니다. DB 드라이버·HTTP 클라이언트가 async 를 지원하지 않으면 동기 함수로 두는 편이 안전합니다.

6. 다른 프레임워크와의 비교

프레임워크	첫 릴리스	성격
Django	2005	"batteries included". ORM · admin · auth 통합. 동기 중심이지만 ASGI 도 지원.
Flask	2010, Armin Ronacher	마이크로 프레임워크. 확장으로 키워 쓰는 방식.
FastAPI	2018	type hint + 자동 문서. ASGI 우선.
Starlette	2018	ASGI 토대. FastAPI 가 그 위에 서 있음.
Litestar	2022 (전 Starlite)	type hint 기반의 또 다른 ASGI 프레임워크.
Sanic	2016	async 우선의 초기 시도 중 하나.

Django 는 풀스택·관리도구 강점. Flask 는 작고 자유로운 확장. FastAPI 는 타입과 OpenAPI 의 결합. 어느 쪽이 우월하기보다 작업 성격에 맞춘 선택입니다.

7. 라우터 분리

# routers/users.py
from fastapi import APIRouter
router = APIRouter(prefix='/users', tags=['users'])

@router.get('/')
def list_users(): ...

# main.py
app.include_router(users.router)

규모가 자라면 도메인 단위로 라우터를 나누는 편이 자연스럽습니다.

8. 응답 모델·상태 코드·백그라운드

@app.post('/items', response_model=ItemOut, status_code=201)
def create(item: ItemIn) -> ItemOut: ...

response_model 을 명시하면 응답 직렬화 스키마가 입력과 분리되고 비밀 필드 노출을 막는 가드 역할도 합니다.

BackgroundTasks 는 응답 후 실행할 가벼운 작업을 위한 도구입니다. 길거나 안정성이 필요한 작업은 별도 큐 (Celery · RQ · Arq) 로 분리하는 편이 적절합니다.

9. 라이프사이클 이벤트

앱 시작·종료 시 한 번씩 실행할 자원 초기화는 lifespan 컨텍스트로 표현합니다.

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.db = await create_pool()
    yield
    await app.state.db.close()

app = FastAPI(lifespan=lifespan)

이전의 @app.on_event("startup") · @app.on_event("shutdown") 데코레이터는 deprecated 로 전환되어 lifespan 이 권장됩니다.

10. OpenAPI 와 /docs

/openapi.json 이 사양 그 자체. /docs 가 Swagger UI, /redoc 이 Redoc 페이지입니다. 운영 환경에서 사양을 외부에 노출하지 않으려면 FastAPI(docs_url=None, redoc_url=None, openapi_url=None) 또는 게이트웨이에서 차단합니다.

11. 실무 — 검증·에러·미들웨어

설계 철학이 코드로 내려오면 매 요청에서 반복되는 네 가지 자리가 있습니다. 검증·에러·속도 제한·CORS 입니다.

검증은 Pydantic 에 위임

타입만으로 부족한 제약은 Field 와 @field_validator 로 모델 안에 적습니다. 핸들러에서 if not name: ... 식으로 검사하면 규칙이 흩어집니다.

from pydantic import BaseModel, Field, field_validator

class ArticleIn(BaseModel):
    title: str = Field(..., max_length=120, description='글 제목')
    slug: str = Field(..., pattern=r'^[a-z0-9-]+$', description='URL 슬러그')

    @field_validator('title')
    @classmethod
    def not_blank(cls, v: str) -> str:
        if not v.strip():
            raise ValueError('제목은 공백일 수 없습니다')
        return v

검증 실패는 FastAPI 가 자동으로 422 와 어느 필드가 왜 틀렸는지를 응답합니다.

모델은 schemas.py 에 모은다

요청·응답 모델을 핸들러 안의 인라인 dict 로 두거나 라우터마다 BaseModel 을 다시 정의하면 같은 스키마가 갈라집니다. 도메인별 schemas.py 한 곳에 모으고 라우터는 그것을 임포트합니다 (폴더 배치는 다음 노트에서 다룹니다).

에러는 HTTPException 으로 정규화

return {"error": "..."} 식 평문 응답은 상태 코드가 여전히 200 이고 스키마도 제각각이 됩니다. 실패는 예외로 올립니다.

from fastapi import HTTPException

if article is None:
    raise HTTPException(status_code=404, detail='글을 찾을 수 없습니다')

예상 못 한 예외까지 한 형태로 응답하려면 전역 핸들러를 둡니다. 스택 트레이스는 로그로만 남기고 본문에 노출하지 않습니다.

from fastapi import Request
from fastapi.responses import JSONResponse

@app.exception_handler(Exception)
async def on_unhandled(request: Request, exc: Exception):
    logger.exception('처리되지 않은 예외')
    return JSONResponse(status_code=500, content={'detail': '서버 오류'})

속도 제한과 CORS 는 미들웨어 층

엔드포인트 남용을 막는 rate limit 은 핸들러마다 카운터를 짜기보다 slowapi 같은 도구의 데코레이터로 선언합니다.

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

@router.get('/search')
@limiter.limit('10/minute')
async def search(request: Request): ...

브라우저에서 다른 출처로 호출받는 API 는 CORSMiddleware 로 허용 출처를 명시합니다. allow_origins=["*"] 는 자격 증명 요청과 함께 쓸 수 없고 범위도 지나치게 넓습니다 — 도메인을 나열합니다.

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=['https://app.example.com'],
    allow_methods=['*'],
    allow_headers=['*'],
)

12. 자주 걸리는 자리

async def 안에서의 블로킹 호출 — requests.get(...) · 동기 ORM 호출. 이벤트 루프가 막힙니다. httpx.AsyncClient · asyncpg · SQLAlchemy 2.x async 같은 비동기 대체를 쓰거나, 라우트를 동기 함수로 두고 별도 스레드 풀에 맡깁니다.

OpenAPI 자동 생성의 한계 — 응답 형태가 동적이거나 멀티 콘텐츠 타입이면 수동으로 보완해야 합니다.

하고픈 말

FastAPI 는 type hint 한 줄에 검증·문서·DI 가 자연스럽게 따라오는 경험이 가장 큰 차별점입니다. Python 의 type hint 가 단순한 주석이 아니라 런타임 도구로 살아 있는 자리입니다. 작은 API 부터 시작해도 큰 비용이 들지 않습니다.

Next

• python-folder-philosophy

FastAPI 공식 · FastAPI GitHub · Starlette 공식 · Pydantic 공식 · ASGI 사양 · Flask 공식 · Django REST framework 을 참고합니다.