김신건의 로그 - 위키 / fastapi

[FastAPI] Async / Sync Endpoints

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI 는 ASGI 프레임워크 이므로 endpoint 를 async def 로 정의해 이벤트 루프에서 실행하거나, def 로 정의해 스레드풀에서 실행할 수 있습니다. 어느 쪽을 선택하는지가 성능과 정확성 모두에 큰 영향을 미칩니다.

async def vs def

@app.get("/sync")
def sync_endpoint():
    # 스레드풀 (기본 40 워커) 에서 실행
    return blocking_operation()

@app.get("/async")
async def async_endpoint():
    # 이벤트 루프에서 실행
    return await async_operation()

결정 트리

await 할 것이 있음 (async DB, async HTTP): async def
Blocking I/O 만 있음 (sync ORM, requests, 파일 IO): def
CPU-bound 계산: def (스레드풀 이용, GIL 은 문제지만 이벤트 루프는 안 막음) or 별도 프로세스풀

잘못된 조합의 위험

위험 1: `async def` 안의 blocking I/O

import time
import requests

@app.get("/danger1")
async def danger1():
    time.sleep(1)                    # 이벤트 루프 1초 정지 (모든 요청 대기)
    return requests.get("...").json()  # 마찬가지 정지

이벤트 루프는 모든 요청을 처리하는 단일 스레드. 여기서 blocking 하면 모든 요청이 대기. p99 latency 급등.

위험 2: `def` 안의 async 코드

@app.get("/danger2")
def danger2():
    result = asyncio.run(some_coro())   # 새 이벤트 루프 생성, 매 요청마다 비용
    return result

asyncio.run 은 새 루프. 이미 부모 프로세스에 루프가 있는데 별도로 만들어 리소스 낭비. 아예 async def 로 바꾸는 게 맞음.

올바른 조합

@app.get("/sync")
def sync_ep():
    return sync_db.query(User).all()   # 스레드풀에서 blocking

@app.get("/async")
async def async_ep(db: Annotated[AsyncSession, Depends(get_async_db)]):
    result = await db.execute(select(User))
    return result.scalars().all()

run_in_threadpool 브릿지

async def 안에서 blocking 함수를 호출해야 할 때:

from fastapi.concurrency import run_in_threadpool

@app.get("/mixed")
async def mixed_ep():
    async_data = await fetch_async()
    blocking_data = await run_in_threadpool(blocking_function)
    return {"a": async_data, "b": blocking_data}

run_in_threadpool 은 함수를 default thread pool (AnyIO 기반) 에서 실행하고 결과를 await 가능한 형태로 반환. 이벤트 루프 blocking 없음.

스레드풀 크기

기본은 40 워커 (Starlette + AnyIO). CPU 코어 수에 무관.

import anyio

@app.on_event("startup")
async def resize_threadpool():
    anyio.to_thread.current_default_thread_limiter().total_tokens = 100

또는 lifespan:

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    limiter = anyio.to_thread.current_default_thread_limiter()
    limiter.total_tokens = 100
    yield

app = FastAPI(lifespan=lifespan)

Dependency 도 async / sync

Dependency 도 함수든 async 함수든 가능. FastAPI 가 알아서 처리.

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

async def get_async_db():    # async dep
    async with AsyncSessionLocal() as db:
        yield db

Async DB (SQLAlchemy 2.0)

from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine, async_sessionmaker

engine = create_async_engine("postgresql+asyncpg://...")
AsyncSessionLocal = async_sessionmaker(engine, expire_on_commit=False)

async def get_async_db() -> AsyncSession:
    async with AsyncSessionLocal() as session:
        yield session

@app.get("/users/{id}")
async def read_user(
    id: int,
    db: Annotated[AsyncSession, Depends(get_async_db)],
):
    result = await db.execute(select(User).where(User.id == id))
    user = result.scalar_one_or_none()
    if not user:
        raise HTTPException(404)
    return user

Async HTTP client (httpx)

import httpx

async def get_http_client() -> httpx.AsyncClient:
    async with httpx.AsyncClient(timeout=10) as client:
        yield client

@app.get("/external/{id}")
async def call_external(
    id: int,
    client: Annotated[httpx.AsyncClient, Depends(get_http_client)],
):
    resp = await client.get(f"https://api.example.com/{id}")
    return resp.json()

성능 팁: AsyncClient 를 lifespan 에서 하나 만들어 dependency 로 재사용 (매 요청 새 클라이언트 생성 회피). Connection pooling.

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    app.state.http = httpx.AsyncClient(timeout=10)
    yield
    await app.state.http.aclose()

async def get_http() -> httpx.AsyncClient:
    return app.state.http

asyncio.gather 로 병렬 요청

import asyncio

@app.get("/aggregate")
async def aggregate(client: Annotated[httpx.AsyncClient, Depends(get_http)]):
    a_task = client.get("https://a")
    b_task = client.get("https://b")
    c_task = client.get("https://c")
    a, b, c = await asyncio.gather(a_task, b_task, c_task)
    return {"a": a.json(), "b": b.json(), "c": c.json()}

세 요청을 병렬로. 순차 대비 3배 빠름 (외부 latency 지배 시).

CPU-bound 처리

CPU-bound 작업은 def + threadpool 이 아니라 process pool 이 정답. GIL 회피.

from concurrent.futures import ProcessPoolExecutor
import asyncio

process_pool = ProcessPoolExecutor(max_workers=4)

async def heavy_compute(x: int) -> int:
    loop = asyncio.get_running_loop()
    return await loop.run_in_executor(process_pool, cpu_heavy_fn, x)

@app.get("/compute/{x}")
async def compute(x: int):
    return await heavy_compute(x)

또는 [[aws-lambda|Lambda]] 로 오프로드.

AnyIO 를 통한 크로스 백엔드

Starlette 는 AnyIO 를 통해 asyncio + trio 모두 지원. FastAPI 의 default 는 asyncio. Trio 사용은 드묾.

언제 어느 것을?

상황	권장
Async DB (SQLAlchemy 2.0 async, Tortoise, Motor)	`async def`
Sync DB (전통 SQLAlchemy, Django ORM)	`def`
Async HTTP (httpx, aiohttp)	`async def`
Sync HTTP (requests)	`def` (또는 httpx.Client)
파일 IO (동기)	`def` 또는 `async def` + `run_in_threadpool`
WebSocket	`async def` (Starlette 요구)
BackgroundTasks	함수 시그니처는 자유롭게
CPU 계산	`def` + process pool
캐시 조회 (Redis async)	`async def`

성능 벤치마크 감

Async ORM + async HTTP: 최대 처리량 (수천 RPS/instance)
Sync ORM + async endpoint: 스레드풀 병목, 40 워커 상한
Sync ORM + sync endpoint: 스레드풀 병목, 40 워커 상한 (같은 임계)
Async endpoint + blocking call in threadpool: 정상 처리

함정

[!WARNING] async def 안에서 절대 time.sleep, requests.get, sync ORM 호출 금지. 이벤트 루프 정지 = p99 폭발.

[!CAUTION] 스레드풀 default 40 은 sync endpoint 병목. 동시 sync 요청이 40 을 넘으면 나머지는 대기. 스레드풀 크기 조정 또는 async 로 이행.

[!WARNING] asyncio.run 을 endpoint 안에서 호출하지 마세요. 이미 있는 루프와 충돌. 그냥 async def 로 만들거나 run_in_threadpool 사용.

[!IMPORTANT] AsyncSession commit/rollback. async with 로 세션을 감싸고 반드시 명시적으로 await session.commit(). Yield 방식 dependency 에서 expire_on_commit=False 를 잊으면 응답 직렬화 시 lazy load 로 async 오류.

[!CAUTION] Middleware 는 async 로 작성. Sync middleware 는 자동으로 스레드풀에 넣기지만 별도 오버헤드.

[FastAPI] Background Tasks

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI 에서 응답 반환 후 실행하는 짧은 작업 은 BackgroundTasks, 장기/신뢰성 있는 작업 은 외부 task queue (Celery, Arq, RQ) 로 오프로드합니다. 두 카테고리를 헷갈리면 데이터 유실, 성능 문제가 발생합니다.

BackgroundTasks (in-process)

응답을 즉시 반환하고, 이어서 같은 프로세스에서 백그라운드 작업 실행.

from fastapi import BackgroundTasks, FastAPI

app = FastAPI()

def send_email(email: str, subject: str, body: str):
    smtp.send(email, subject, body)   # 몇 초 걸리는 blocking 호출

@app.post("/subscribe")
def subscribe(email: str, background_tasks: BackgroundTasks):
    save_subscription(email)
    background_tasks.add_task(send_email, email, "Welcome", "Hi!")
    return {"status": "subscribed"}

동작:

save_subscription 실행
응답 (200) 즉시 반환
이후 이벤트 루프가 send_email 실행

async / sync 모두 지원

async def async_task(x: int):
    await asyncio.sleep(1)
    print(x)

background_tasks.add_task(async_task, 42)

Sync 함수는 스레드풀에서, async 함수는 이벤트 루프에서 실행.

Dependency 와 조합

def get_notifier() -> Notifier:
    return Notifier()

def send_notification(notifier: Notifier, user_id: int, message: str):
    notifier.send(user_id, message)

@app.post("/notify")
def notify(
    user_id: int,
    message: str,
    background_tasks: BackgroundTasks,
    notifier: Annotated[Notifier, Depends(get_notifier)],
):
    background_tasks.add_task(send_notification, notifier, user_id, message)
    return {"queued": True}

주의: dependency 로 얻은 리소스 (DB 세션 등) 는 응답 시점에 이미 닫힘. Background task 안에서 재사용 불가. 새 세션을 명시적으로 열어야 함.

BackgroundTasks 의 한계

BackgroundTasks 는 간단하고 실패해도 큰 문제 없는 작업 에만 씁니다.

동일 프로세스: worker 프로세스가 죽으면 태스크 잃음
재시도 없음: 실패해도 그냥 로그
큐 상태 관찰 불가: 백로그, 실패 카운트 없음
분산 없음: worker 확장 불가
응답 시 이벤트 루프 사용: async 태스크는 이벤트 루프 부담

적합: 이메일 발송 시도 (실패해도 재시도 없어도 됨), 캐시 warm, 로그 전송. 부적합: 결제, 회계, 신뢰성 요구 작업. 이 경우 반드시 외부 큐.

외부 Task Queue

Celery (전통적)

가장 널리 쓰이는 Python task queue.

# tasks.py
from celery import Celery

celery_app = Celery("myapp", broker="redis://localhost:6379/0", backend="redis://localhost:6379/1")

@celery_app.task(bind=True, max_retries=3)
def process_payment(self, order_id: int):
    try:
        payment_service.charge(order_id)
    except TemporaryError as exc:
        raise self.retry(exc=exc, countdown=60)

# main.py
from tasks import process_payment

@app.post("/checkout")
def checkout(order: Order):
    save_order(order)
    process_payment.delay(order.id)   # Celery 워커가 처리
    return {"order_id": order.id, "status": "pending"}

실행:

celery -A tasks worker --loglevel=info --concurrency=4
celery -A tasks beat --loglevel=info      # 스케줄러
celery -A tasks flower                    # 모니터링 UI

강점: 성숙, 방대한 기능 (retry, chain, group, chord, periodic tasks, …), 방대한 문서 약점: async 지원 미흡 (sync worker 위주), 무거움, 설정 복잡

Arq (async 지향)

Redis 백엔드, asyncio native.

# worker.py
from arq import create_pool
from arq.connections import RedisSettings

async def send_email(ctx, email: str, subject: str):
    async with aiohttp.ClientSession() as session:
        await session.post("https://mail-api/send", json={"to": email, "subject": subject})

class WorkerSettings:
    functions = [send_email]
    redis_settings = RedisSettings(host="localhost")

# main.py
from arq import create_pool

redis = None

@app.on_event("startup")
async def startup():
    global redis
    redis = await create_pool(RedisSettings())

@app.post("/subscribe")
async def subscribe(email: str):
    await redis.enqueue_job("send_email", email, "Welcome")
    return {"queued": True}

실행:

arq worker.WorkerSettings

강점: async-first, 가볍고 빠름, FastAPI 와 자연스러운 통합 약점: Celery 대비 기능/생태계 좁음

RQ (Redis Queue)

가장 단순.

from rq import Queue
from redis import Redis

redis_conn = Redis()
queue = Queue(connection=redis_conn)

def my_task(x):
    return x * 2

@app.post("/enqueue")
def enqueue(x: int):
    job = queue.enqueue(my_task, x)
    return {"job_id": job.id}

실행: rq worker

강점: 매우 단순, 배우기 쉬움 약점: 기능 제한, sync 위주

Dramatiq

Celery 대안, 더 단순한 API.

큐 선택 가이드

상황	권장
간단, 실패해도 OK, 응답 후 즉시 실행	BackgroundTasks
신뢰성 필요, sync 워크플로	Celery
async 워크플로, FastAPI 호환	Arq
최소 설정, 프로토타입	RQ
대규모, 스케줄, DAG	Celery or Airflow/Prefect
마이크로서비스, 이벤트 소싱	Kafka + consumer

실시간 진행 상황

BackgroundTasks 로 시작한 작업의 진행 상황을 클라이언트에 알려야 한다면:

WebSocket (fastapi-websockets): 실시간 push
SSE (Server-Sent Events):

from fastapi import Request
from sse_starlette.sse import EventSourceResponse

@app.get("/progress/{task_id}")
async def progress(task_id: str, request: Request):
    async def event_generator():
        while True:
            if await request.is_disconnected():
                break
            status = get_task_status(task_id)
            yield {"data": status}
            if status["done"]:
                break
            await asyncio.sleep(1)
    return EventSourceResponse(event_generator())

Polling: 상태를 DB/Redis 저장, 클라이언트가 주기적 GET

Idempotency

Task 는 대개 재시도됩니다. Idempotent (여러 번 실행해도 같은 결과) 하게 작성:

@celery_app.task(bind=True, max_retries=3)
def send_email(self, message_id: str, to: str):
    if EmailLog.exists(message_id=message_id):
        return   # 이미 처리됨
    smtp.send(to, ...)
    EmailLog.create(message_id=message_id)

message_id 를 client 가 생성해 넘겨야 진정한 idempotency 보장.

함정

[!WARNING] BackgroundTasks 로 신뢰성 있는 작업을 하지 마세요. 프로세스가 죽으면 잃음. 실패 재시도 없음. Celery/Arq 로 이관.

[!CAUTION] Background task 안에서 request-scoped dependency 사용 불가. DB 세션은 응답 시점에 이미 닫힘. 새 세션을 명시적으로.

[!WARNING] Celery .delay() 호출은 broker 에 실제 저장 후 반환. Broker 가 죽으면 실패. Redis persistence 또는 결제 등 중요한 작업은 outbox pattern.

[!IMPORTANT] Async task 는 async worker 필요. Celery 는 gevent/eventlet 로 async 흉내내지만 완벽하지 않음. Async-first 워크플로는 Arq.

[!CAUTION] Serialization. Task 인자는 JSON 직렬화 가능해야 함. Datetime, UUID, Pydantic 모델은 문자열로 변환 후 전달. 큰 객체는 DB 저장 후 ID 전달.

[FastAPI] Dependency Injection

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI Dependency Injection 은 Depends() 로 함수를 endpoint 에 자동 주입하는 시스템입니다. DB 세션, 인증 사용자, 설정, 서비스 계층 등을 endpoint 의 파라미터로 선언하면 FastAPI 가 알아서 해결/캐싱/lifecycle 관리를 수행합니다.

Java Spring / Angular 의 DI 컨테이너보다 훨씬 가벼우며, 함수 시그니처 = 스펙 원칙에 부합합니다.

기본 사용

from fastapi import Depends, FastAPI

app = FastAPI()

def common_query(q: str | None = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items/")
def read_items(commons: dict = Depends(common_query)):
    return commons

common_query 는 요청마다 호출되고 그 반환값이 commons 로 주입됩니다.

Type hint 지원

Python 3.9+ Annotated 로 더 명확한 스타일:

from typing import Annotated

CommonsDep = Annotated[dict, Depends(common_query)]

@app.get("/items/")
def read_items(commons: CommonsDep):
    return commons

Class-based Dependency

class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
        self.q = q
        self.skip = skip
        self.limit = limit

@app.get("/items/")
def read_items(commons: CommonQueryParams = Depends()):
    return {"skip": commons.skip, "limit": commons.limit}

Depends() 인자 생략 시 클래스 자체를 factory 로 사용.

Sub-dependency

Dependency 가 또 다른 dependency 를 가질 수 있음. 트리 구조.

def query_extractor(q: str | None = None):
    return q

def query_or_cookie_extractor(
    q: Annotated[str | None, Depends(query_extractor)],
    last_query: Annotated[str | None, Cookie()] = None,
):
    if not q:
        return last_query
    return q

@app.get("/items/")
def read_items(query: Annotated[str, Depends(query_or_cookie_extractor)]):
    return {"q_or_cookie": query}

같은 dependency 가 한 요청에서 여러 번 참조되어도 캐시 되어 한 번만 호출.

Cache 비활성화

Depends(some_dep, use_cache=False)

Yield-based (Cleanup)

with 를 대신하는 lifecycle. DB 세션, 파일 핸들 등에 유용.

from sqlalchemy.orm import Session

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

@app.get("/users/{id}")
def read_user(id: int, db: Annotated[Session, Depends(get_db)]):
    return db.query(User).get(id)

try/finally 는 endpoint 정상/예외 종료 모두에서 실행. 예외는 위로 전파.

Async yield

async def get_async_db():
    async with AsyncSession(engine) as session:
        yield session

Router / App level dependency

특정 endpoint 가 아니라 라우터 전체 / 앱 전체에 걸어 인증/로깅 등 공통 처리.

from fastapi import Depends

def verify_token(x_token: Annotated[str, Header()]) -> None:
    if x_token != "expected":
        raise HTTPException(status_code=401)

router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_token)],   # 라우터 전체
)

app = FastAPI(dependencies=[Depends(logging_middleware)])  # 앱 전체

이 경우 dependency 의 반환값은 endpoint 에 주입되지 않고 side effect (검증, 로깅) 만 수행.

인증 (OAuth2 / JWT 예시)

from fastapi.security import OAuth2PasswordBearer
from jose import jwt

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")

def get_current_user(token: Annotated[str, Depends(oauth2_scheme)]) -> User:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
        user_id = payload["sub"]
    except jwt.JWTError:
        raise HTTPException(status_code=401, detail="Invalid token")
    user = db.query(User).get(user_id)
    if not user:
        raise HTTPException(status_code=401)
    return user

def get_current_admin(user: Annotated[User, Depends(get_current_user)]) -> User:
    if not user.is_admin:
        raise HTTPException(status_code=403)
    return user

@app.get("/admin/dashboard")
def dashboard(admin: Annotated[User, Depends(get_current_admin)]):
    return {"welcome": admin.email}

OAuth2PasswordBearer 는 자동으로 Swagger UI 에 “Authorize” 버튼 추가.

dependency_overrides (테스트)

Endpoint 코드를 안 바꾸고 테스트에서 dependency 를 교체.

from fastapi.testclient import TestClient

def override_get_db():
    db = TestingSessionLocal()
    try:
        yield db
    finally:
        db.close()

app.dependency_overrides[get_db] = override_get_db
client = TestClient(app)

response = client.get("/users/1")

# 테스트 후 clear
app.dependency_overrides = {}

핵심 강점: 프로덕션 코드는 순수 함수 시그니처, 테스트 인프라는 별도 파일.

Global State Anti-pattern

FastAPI DI 는 global state 를 지양 하는 방향. 다음은 안 좋은 예:

# BAD: global 로 db 를 직접 참조
db_session = SessionLocal()

@app.get("/users/{id}")
def read_user(id: int):
    return db_session.query(User).get(id)   # thread-unsafe, 테스트 불가

DI 사용:

# GOOD
@app.get("/users/{id}")
def read_user(id: int, db: Annotated[Session, Depends(get_db)]):
    return db.query(User).get(id)

서비스 계층 DI

class UserService:
    def __init__(self, db: Session, cache: Redis):
        self.db = db
        self.cache = cache

    def get(self, user_id: int) -> User:
        cached = self.cache.get(f"user:{user_id}")
        if cached:
            return User.model_validate_json(cached)
        user = self.db.query(User).get(user_id)
        self.cache.set(f"user:{user_id}", user.model_dump_json(), ex=300)
        return user

def get_user_service(
    db: Annotated[Session, Depends(get_db)],
    cache: Annotated[Redis, Depends(get_redis)],
) -> UserService:
    return UserService(db, cache)

@app.get("/users/{id}")
def read_user(
    id: int,
    users: Annotated[UserService, Depends(get_user_service)],
):
    return users.get(id)

Java Spring 스타일 3-layer (Controller / Service / Repository) 를 FastAPI 스타일로 옮긴 예.

Depends() 실행 순서

한 요청에서:

Path parameter, query parameter, header 파싱
Dependency 트리 topological sort
Root dependency 부터 실행, 캐시 활용
Endpoint 함수 실행
Yield-based dependency 의 cleanup (역순)

Background Task 와 DI

from fastapi import BackgroundTasks

def send_notification(email: str, message: str, service: EmailService):
    service.send(email, message)

@app.post("/send")
def send(
    background_tasks: BackgroundTasks,
    email: str,
    service: Annotated[EmailService, Depends(get_email_service)],
):
    background_tasks.add_task(send_notification, email, "hi", service)
    return {"ok": True}

주의: BackgroundTasks 는 응답 반환 후 실행. DB 세션 dependency 는 응답 시점에 이미 닫힘 -> background 에서 사용 시 새 세션 필요.

함정

[!WARNING] Depends() 는 Python 인자 기본값 자리에만. def foo(x: Depends(dep)) 는 문법 오류. def foo(x = Depends(dep)) 또는 Annotated[X, Depends(dep)].

[!CAUTION] Yield-based dependency 안의 예외 처리. yield 이전 예외는 endpoint 로 전파, yield 이후 (finally 안) 예외는 로그만 되고 응답 이후. Cleanup 실패는 조용히 묻힘.

[!WARNING] DB 세션 dependency 를 async 로 감쌀 때 async yield 를 써야 함. def get_db + async def endpoint 조합에서 세션 close 가 이벤트 루프 안에서 발생 -> blocking.

[!IMPORTANT] dependency_overrides 는 앱 상태. 테스트 종료 시 반드시 clear. pytest fixture 로 setup/teardown.

[!CAUTION] Router 레벨 dependency 는 endpoint 파라미터로 주입 안 됨. 반환값이 필요하면 endpoint 시그니처에도 명시.

[FastAPI] Deployment (Uvicorn, Gunicorn, Docker)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI 배포는 ASGI 서버 (Uvicorn) + 프로세스 관리자 (Gunicorn 또는 Uvicorn 자체) + 컨테이너 (Docker) + 오케스트레이터 (Kubernetes/ECS) 계층으로 구성됩니다. 각 계층의 역할과 트레이드오프를 정확히 이해해야 프로덕션 안정성이 확보됩니다.

구성 계층

[Client]
   ↓ HTTPS
[Load Balancer / CDN (ALB, CloudFront, Nginx)]
   ↓ HTTP
[프로세스 관리자 (Gunicorn or Uvicorn --workers)]
   ↓ multiple processes
[Uvicorn worker (ASGI server, per process)]
   ↓
[FastAPI app]

Uvicorn 단독 (개발/간단 프로덕션)

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

--workers: 프로세스 수 (기본 1)
--reload: 개발용 자동 재시작 (프로덕션 X)
--log-level: debug/info/warning/error/critical
--access-log / --no-access-log
--proxy-headers --forwarded-allow-ips="*": 리버스 프록시 뒤 배포 시

Uvicorn —workers vs Gunicorn

Uvicorn —workers: multiprocessing 프로세스 매니저. 단순, 별도 의존성 없음.
Gunicorn + Uvicorn workers: Gunicorn 이 프로세스 라이프사이클 (graceful reload, timeout, pre-fork) 관리, Uvicorn 이 각 프로세스 안에서 ASGI 서버 역할.

Gunicorn 의 장점: signal 처리 (SIGHUP graceful reload), timeout, memory leak worker 재활용 등 성숙한 기능.

Gunicorn + Uvicorn worker

pip install gunicorn uvicorn[standard]

gunicorn myapp.main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000 \
  --timeout 120 \
  --graceful-timeout 30 \
  --keep-alive 5 \
  --access-logfile - \
  --error-logfile -

-w: worker 프로세스 수. 일반 공식 2 * CPU + 1, async 워크로드는 CPU 개수 근방.
-k uvicorn.workers.UvicornWorker: Uvicorn 을 worker 로
--timeout: worker 가 응답 못 하면 kill (기본 30초)
--graceful-timeout: shutdown 시 진행 중 요청 완료 대기
--keep-alive: HTTP keep-alive 연결 유지 초

UvicornWorker vs UvicornH11Worker

UvicornWorker (기본): httptools + uvloop 로 성능 최적
UvicornH11Worker: pure Python h11. 특수 환경 (uvloop 미지원) 용

Worker 수 결정

CPU-bound async 앱:

이벤트 루프가 CPU 를 대부분 소비 -> worker 수 = CPU 개수

IO-bound async 앱:

이벤트 루프가 대부분 대기 -> worker 수 = CPU 개수 (많이 늘려도 이득 적음)

Sync 앱 (blocking IO):

Worker 하나에 스레드풀 40 워커. worker 수 = CPU 개수
총 동시 요청 처리 = workers × threadpool

메모리 제약:

각 worker 는 별도 프로세스 -> 앱 메모리 × worker 수
ML 모델 로드 앱은 worker 수를 신중히 (또는 shared memory)

신호 처리 & graceful shutdown

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(app: FastAPI):
    # startup
    app.state.db = await create_engine()
    app.state.http = httpx.AsyncClient()
    yield
    # shutdown
    await app.state.http.aclose()
    await app.state.db.dispose()

app = FastAPI(lifespan=lifespan)

Gunicorn 이 SIGTERM 을 받으면 새 요청 accept 중지, 진행 중 요청 완료 대기, lifespan shutdown 실행.

Kubernetes 는 SIGTERM 을 pod 종료 전에 보냄. terminationGracePeriodSeconds 를 Gunicorn --graceful-timeout 보다 크게.

Docker

최소 Dockerfile

FROM python:3.12-slim

WORKDIR /app

# 의존성 캐시
COPY pyproject.toml uv.lock ./
RUN pip install --no-cache-dir uv && \
    uv sync --frozen --no-dev

# 소스
COPY src /app/src

# non-root user
RUN useradd -m app && chown -R app:app /app
USER app

EXPOSE 8000

CMD ["uv", "run", "uvicorn", "myapp.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

Multi-stage build (이미지 크기 최소화)

# --- builder ---
FROM python:3.12-slim AS builder
WORKDIR /app
RUN pip install uv
COPY pyproject.toml uv.lock ./
RUN uv sync --frozen --no-dev

# --- runtime ---
FROM python:3.12-slim
WORKDIR /app
COPY --from=builder /app/.venv /app/.venv
COPY src /app/src
ENV PATH="/app/.venv/bin:$PATH"
CMD ["uvicorn", "myapp.main:app", "--host", "0.0.0.0", "--port", "8000"]

이미지 스택 선택

python:3.12-slim: 표준, ~130 MB base. glibc 사용.
python:3.12-alpine: 가벼움 (~55 MB base). musl libc, 일부 wheel 미지원.
gcr.io/distroless/python3-debian12: 최소, non-root, shell 없음. 디버그 어려움.

추천: python:3.12-slim + multi-stage 로 100-200 MB 최종 이미지.

Kubernetes 배포

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: app
          image: myrepo/myapp:1.0
          ports: [{containerPort: 8000}]
          resources:
            requests: {cpu: 500m, memory: 512Mi}
            limits: {cpu: 2, memory: 2Gi}
          livenessProbe:
            httpGet: {path: /health/live, port: 8000}
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet: {path: /health/ready, port: 8000}
            initialDelaySeconds: 5
            periodSeconds: 5
          startupProbe:
            httpGet: {path: /health/startup, port: 8000}
            failureThreshold: 30
            periodSeconds: 5
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "5"]   # LB 에서 빠지는 시간

Probe 엔드포인트

@app.get("/health/live", include_in_schema=False)
def liveness():
    return {"status": "ok"}

@app.get("/health/ready", include_in_schema=False)
async def readiness(
    db: Annotated[AsyncSession, Depends(get_async_db)]
):
    await db.execute(text("SELECT 1"))
    return {"status": "ok"}

@app.get("/health/startup", include_in_schema=False)
def startup():
    return {"status": "ready"}

Liveness: 앱이 살아있는가 (fail 시 재시작)
Readiness: 트래픽을 받을 수 있는가 (fail 시 LB 에서 제거)
Startup: 초기화 중 (다른 probe 지연)

Reverse Proxy 설정

Nginx

upstream fastapi {
    server 127.0.0.1:8000;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name api.example.com;

    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;

    location / {
        proxy_pass http://fastapi;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;         # WebSocket
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600;
        proxy_buffering off;                             # SSE
    }
}

FastAPI 는 --proxy-headers --forwarded-allow-ips="*" 로 X-Forwarded-* 신뢰.

AWS ALB

Health check path: /health/ready
Idle timeout: 60초 (WebSocket 은 확장)
Stickiness: WebSocket 이 프로세스 로컬 상태 유지 시

로깅 & 관측

구조화 로그

import logging
import json
from pythonjsonlogger import jsonlogger

handler = logging.StreamHandler()
handler.setFormatter(jsonlogger.JsonFormatter(
    "%(asctime)s %(name)s %(levelname)s %(message)s"
))
logging.basicConfig(handlers=[handler], level=logging.INFO)

CloudWatch, Datadog, Loki 등이 JSON 로그를 파싱 가능.

OpenTelemetry

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
opentelemetry-instrument uvicorn myapp.main:app

FastAPI, SQLAlchemy, HTTP client 등 자동 계측.

Sentry

import sentry_sdk
from sentry_sdk.integrations.fastapi import FastApiIntegration

sentry_sdk.init(
    dsn="https://xxx@sentry.io/yyy",
    traces_sample_rate=0.1,
    integrations=[FastApiIntegration()],
)

환경 변수 & Secrets

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str
    secret_key: str
    debug: bool = False

    class Config:
        env_file = ".env"

Kubernetes: Secret 리소스로 마운트. AWS: Secrets Manager / SSM Parameter Store.

성능 팁

--http httptools, --loop uvloop: Uvicorn 기본이지만 uvicorn[standard] 필요
--limit-concurrency N: 동시 요청 상한 (backpressure)
--limit-max-requests N: worker 재시작 트리거 (메모리 누수 완화)
Prefork with LazyLoad: ML 모델은 fork 후 로드 (COW 활용) 또는 각 worker 개별 로드
HTTP/2: Uvicorn 은 미지원. Hypercorn 사용 또는 프록시 (Nginx/Envoy) 에서 종단

함정

[!WARNING] --reload 는 개발만. 프로덕션에서 코드 변경 감시로 부하 + 리소스 누수.

[!CAUTION] worker_class 잘못 지정. Sync worker (sync) 는 FastAPI 부적합. 반드시 uvicorn.workers.UvicornWorker.

[!WARNING] Signal 처리 misconfig. Gunicorn --graceful-timeout < Kubernetes terminationGracePeriodSeconds 여야 in-flight 요청 완료.

[!IMPORTANT] 모델 로딩은 lifespan startup. Endpoint 별 매 요청 로드는 재앙. 앱 시작 시 한 번, app.state 에 저장.

[!CAUTION] 컨테이너 안에서 USER root 유지 위험. non-root user 사용, non-privileged port (8000+) 사용.

[FastAPI] Middleware

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI Middleware 는 모든 요청과 응답을 가로채 로깅, 인증, 압축, CORS 등 공통 처리를 하는 계층입니다. Starlette 의 ASGI middleware 를 그대로 사용하며, 함수 스타일 (@app.middleware("http")) 과 클래스 스타일 (app.add_middleware) 두 가지 API 를 제공합니다.

함수 스타일

import time
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

call_next(request) 는 다음 미들웨어 또는 endpoint 로 요청을 넘김. 응답이 돌아오면 수정 후 반환.

클래스 스타일

from starlette.middleware.cors import CORSMiddleware

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

실행 순서

등록 순서의 역순으로 outer -> inner 로 요청 시. 응답은 inner -> outer.

app.add_middleware(A)  # 마지막에 나가는 outer
app.add_middleware(B)
app.add_middleware(C)  # 처음 들어오는 inner

요청 흐름: C -> B -> A -> endpoint. 응답 흐름: endpoint -> A -> B -> C.

따라서: 인증은 outer 에 (요청 초입에서 검증), 로깅은 inner (엔드포인트 근처).

내장 미들웨어

CORSMiddleware

Cross-Origin Resource Sharing. 브라우저의 same-origin policy 를 위한 헤더 추가.

from starlette.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com", "https://admin.example.com"],
    allow_origin_regex=r"https://.*\.example\.com",  # 대안
    allow_credentials=True,        # cookie 허용
    allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH"],
    allow_headers=["*"],
    expose_headers=["X-Custom-Header"],
    max_age=600,                   # preflight 캐시 (초)
)

주의: allow_credentials=True + allow_origins=["*"] 조합은 브라우저가 거부. 명시적 origin 필요.

GZipMiddleware

응답 gzip 압축. 클라이언트가 Accept-Encoding: gzip 을 보낼 때만 적용.

from starlette.middleware.gzip import GZipMiddleware

app.add_middleware(GZipMiddleware, minimum_size=1000, compresslevel=6)

minimum_size: 이 크기 이상만 압축 (작은 응답은 압축 오버헤드가 이득 초과)
compresslevel: 1-9, 6 이 기본. 크기/속도 트레이드오프.

TrustedHostMiddleware

Host header 검증. Host header 주입 공격 방어.

from starlette.middleware.trustedhost import TrustedHostMiddleware

app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com"],
)

허용되지 않은 호스트는 400 반환.

HTTPSRedirectMiddleware

HTTP -> HTTPS 리디렉트.

from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware

app.add_middleware(HTTPSRedirectMiddleware)

주의: 프록시 (ALB, CloudFront) 뒤에서는 X-Forwarded-Proto 를 신뢰하기 위해 프록시 미들웨어 필요. Uvicorn 의 --proxy-headers 옵션과 조합.

SessionMiddleware

서버 side 없는 서명 쿠키 세션.

from starlette.middleware.sessions import SessionMiddleware

app.add_middleware(
    SessionMiddleware,
    secret_key="your-secret-key",
    session_cookie="session",
    max_age=14 * 24 * 3600,   # 14일
    same_site="lax",
    https_only=True,
)

@app.get("/set")
def set_session(request: Request):
    request.session["user_id"] = 42
    return {"ok": True}

@app.get("/get")
def get_session(request: Request):
    return {"user_id": request.session.get("user_id")}

Custom Middleware 패턴

로깅 미들웨어

import logging, time, uuid

logger = logging.getLogger("access")

@app.middleware("http")
async def log_requests(request: Request, call_next):
    request_id = str(uuid.uuid4())
    start = time.time()

    logger.info(f"[{request_id}] {request.method} {request.url.path}")

    response = await call_next(request)

    duration = time.time() - start
    logger.info(
        f"[{request_id}] {request.method} {request.url.path} "
        f"-> {response.status_code} ({duration:.3f}s)"
    )
    response.headers["X-Request-ID"] = request_id
    return response

요청 ID 전파

from contextvars import ContextVar

request_id_ctx: ContextVar[str] = ContextVar("request_id", default="")

@app.middleware("http")
async def request_id_middleware(request: Request, call_next):
    rid = request.headers.get("X-Request-ID") or str(uuid.uuid4())
    token = request_id_ctx.set(rid)
    try:
        response = await call_next(request)
        response.headers["X-Request-ID"] = rid
        return response
    finally:
        request_id_ctx.reset(token)

logger 에서 request_id_ctx.get() 로 참조. 분산 트레이싱의 시발점.

인증 미들웨어

미들웨어보다는 [[fastapi-dependency-injection|Dependency]] 로 하는 것이 표준. 다만 앱 전역 인증이 필요하면:

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.responses import JSONResponse

class AuthMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        # 인증 예외 경로
        if request.url.path in {"/health", "/docs", "/openapi.json"}:
            return await call_next(request)

        token = request.headers.get("Authorization")
        if not token:
            return JSONResponse({"detail": "Missing token"}, status_code=401)

        try:
            user = validate_token(token)
        except InvalidToken:
            return JSONResponse({"detail": "Invalid token"}, status_code=401)

        request.state.user = user      # request.state 로 전달
        return await call_next(request)

app.add_middleware(AuthMiddleware)

Endpoint 에서 request.state.user 로 접근. Dependency 조합도 가능.

Rate limiter

from collections import defaultdict
import time

class RateLimiter(BaseHTTPMiddleware):
    def __init__(self, app, calls: int = 100, period: int = 60):
        super().__init__(app)
        self.calls = calls
        self.period = period
        self.clients: dict[str, list[float]] = defaultdict(list)

    async def dispatch(self, request: Request, call_next):
        client_id = request.client.host
        now = time.time()
        self.clients[client_id] = [
            t for t in self.clients[client_id] if now - t < self.period
        ]
        if len(self.clients[client_id]) >= self.calls:
            return JSONResponse({"detail": "Rate limit exceeded"}, status_code=429)
        self.clients[client_id].append(now)
        return await call_next(request)

app.add_middleware(RateLimiter, calls=100, period=60)

주의: 이 예시는 단일 프로세스용. 프로덕션은 Redis 기반 (slowapi, fastapi-limiter) 사용.

Exception Handler

Middleware 는 아니지만 유사 위치:

from fastapi.responses import JSONResponse

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    return JSONResponse({"error": str(exc)}, status_code=400)

@app.exception_handler(404)
async def not_found_handler(request: Request, exc):
    return JSONResponse({"detail": "Custom 404"}, status_code=404)

Middleware 성능 팁

Async 로 작성: sync middleware 는 스레드풀 오버헤드
call_next 는 반드시 await: 안 하면 응답 못 감
Response body 를 읽으면 새 Response 반환: StreamingResponse 재구성 필요
너무 많은 미들웨어: 스택 오버헤드. 필수만.

함정

[!WARNING] 미들웨어에서 request body 를 여러 번 읽으면 안 됩니다. Starlette Request 는 stream. await request.body() 는 한 번만. 다시 읽어야 하면 캐시.

[!CAUTION] BaseHTTPMiddleware 는 응답 스트리밍을 방해할 수 있음. StreamingResponse 를 사용하는 endpoint 앞에서 이 미들웨어를 쓰면 응답 전체를 버퍼링. Pure ASGI middleware 로 대체 검토.

[!WARNING] CORS + credentials + wildcard 는 브라우저가 막습니다. 명시적 origin 나열.

[!IMPORTANT] 미들웨어 예외. call_next 가 예외를 던지면 후속 미들웨어의 응답 처리 로직이 실행 안 됨. try/except 로 감싸거나 exception handler 사용.

[!CAUTION] 미들웨어 순서. 인증 -> 로깅 -> CORS 순서에 따라 프리플라이트 요청이 인증 전에 통과하지 못하는 문제. CORS 는 대개 outermost.

[FastAPI] Pydantic Integration

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI + Pydantic 은 요청/응답의 타입 검증, 직렬화, JSON Schema 생성 을 위한 통합입니다. Pydantic v2 는 Rust 코어 (pydantic-core) 로 v1 대비 5-50배 성능 향상되었고, FastAPI 0.100+ 부터 완전히 지원됩니다.

BaseModel 기본

from pydantic import BaseModel, Field, EmailStr
from datetime import datetime

class UserCreate(BaseModel):
    email: EmailStr
    password: str = Field(..., min_length=8, max_length=128)
    name: str = Field(..., max_length=50)
    age: int = Field(default=0, ge=0, le=150)
    created_at: datetime = Field(default_factory=datetime.utcnow)

... (Ellipsis): required
default 또는 default_factory: optional
ge, le, gt, lt, min_length, max_length, pattern: validation
EmailStr: email-validator 패키지 필요

Field 상세 옵션

class Product(BaseModel):
    name: str = Field(
        ...,
        title="상품명",
        description="상품의 고유 이름",
        example="MacBook Pro",
        min_length=1,
        max_length=100,
    )
    price: float = Field(..., gt=0, description="가격 (KRW)")
    tags: list[str] = Field(default_factory=list, max_length=10)

title, description, example 은 OpenAPI 문서에 그대로 노출.

중첩 모델

class Address(BaseModel):
    city: str
    zip_code: str

class User(BaseModel):
    name: str
    address: Address
    friends: list["User"] = []       # 순환 참조 (forward ref)

Pydantic v2 는 forward ref 자동 해결. model_rebuild() 는 대개 불필요.

Validator (v2)

field_validator (개별 필드)

from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str

    @field_validator("name")
    @classmethod
    def name_must_contain_space(cls, v: str) -> str:
        if " " not in v:
            raise ValueError("name must contain a space")
        return v.title()

mode="before": 파싱 전 (raw 값 접근)
mode="after" (기본): 파싱 후 (타입 검증 후)

model_validator (모델 전체)

from pydantic import model_validator

class User(BaseModel):
    password: str
    password_confirm: str

    @model_validator(mode="after")
    def passwords_match(self):
        if self.password != self.password_confirm:
            raise ValueError("passwords do not match")
        return self

Computed Field (v2)

응답에만 나타나는 계산 필드:

from pydantic import computed_field

class User(BaseModel):
    first_name: str
    last_name: str

    @computed_field
    @property
    def full_name(self) -> str:
        return f"{self.first_name} {self.last_name}"

Config (v2: model_config)

from pydantic import BaseModel, ConfigDict

class User(BaseModel):
    model_config = ConfigDict(
        str_strip_whitespace=True,     # 문자열 자동 trim
        str_min_length=1,
        populate_by_name=True,          # alias 와 원본 필드명 모두 허용
        from_attributes=True,           # ORM 모드 (SQLAlchemy)
        json_schema_extra={
            "examples": [
                {"email": "a@b.com", "name": "Kim"}
            ]
        },
    )

v1 의 class Config 는 deprecated. ConfigDict 사용.

Alias (필드명 매핑)

class User(BaseModel):
    user_name: str = Field(..., alias="userName")   # camelCase JSON

    model_config = ConfigDict(populate_by_name=True)

요청 JSON 이 {"userName": "..."} 형태여도 파싱. 응답도 userName 로 직렬화.

전역 alias generator:

from pydantic.alias_generators import to_camel

class User(BaseModel):
    model_config = ConfigDict(
        alias_generator=to_camel,
        populate_by_name=True,
    )
    user_name: str
    email: str

Response Model

FastAPI 의 response_model 은 Pydantic 모델로 응답 필터/검증.

class UserIn(BaseModel):
    email: str
    password: str

class UserOut(BaseModel):
    id: int
    email: str

@app.post("/users/", response_model=UserOut)
def create_user(user: UserIn) -> UserIn:
    # 저장 후 반환. password 는 자동 제거.
    saved = save_to_db(user)
    return saved

UserOut 스키마와 다른 필드는 응답에서 자동 제외.

response_model_exclude_unset

@app.get("/users/{id}", response_model=User, response_model_exclude_unset=True)
def read_user(id: int):
    return db.query(User).get(id)

None 이 아닌 실제로 설정된 필드만 응답. sparse 응답에 유용.

ORM 모드 (from_attributes)

SQLAlchemy 등 ORM 객체를 Pydantic 으로 자동 변환:

from sqlalchemy.orm import Mapped

class UserORM(Base):
    __tablename__ = "users"
    id: Mapped[int]
    email: Mapped[str]

class User(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    email: str

user_orm = db.query(UserORM).first()
user_pydantic = User.model_validate(user_orm)   # ORM -> Pydantic

FastAPI response_model 에서 return 값이 ORM 객체여도 자동 변환.

Discriminator (v2)

Tagged union:

from typing import Literal
from pydantic import BaseModel, Field
from typing import Annotated, Union

class Cat(BaseModel):
    pet_type: Literal["cat"]
    meow: str

class Dog(BaseModel):
    pet_type: Literal["dog"]
    bark: str

Pet = Annotated[Union[Cat, Dog], Field(discriminator="pet_type")]

class Owner(BaseModel):
    pet: Pet

{"pet_type": "cat", "meow": "..."} 는 자동으로 Cat 으로 파싱.

pydantic-settings (설정 관리)

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_prefix="APP_",
    )

    database_url: str
    secret_key: str
    debug: bool = False

settings = Settings()

환경변수 APP_DATABASE_URL 이 database_url 필드로 매핑. .env 파일도 자동 로딩.

FastAPI 에서 DI 로 사용:

from functools import lru_cache

@lru_cache
def get_settings() -> Settings:
    return Settings()

@app.get("/info")
def info(settings: Settings = Depends(get_settings)):
    return {"debug": settings.debug}

JSON Schema 생성

schema = User.model_json_schema()

FastAPI 는 이 스키마를 OpenAPI components/schemas 에 자동 등록.

v1 -> v2 마이그레이션

v1	v2
`class Config:`	`model_config = ConfigDict(...)`
`.dict()`	`.model_dump()`
`.json()`	`.model_dump_json()`
`.parse_obj(x)`	`.model_validate(x)`
`.parse_raw(s)`	`.model_validate_json(s)`
`@validator`	`@field_validator`
`@root_validator`	`@model_validator`
`orm_mode=True`	`from_attributes=True`
`allow_population_by_field_name=True`	`populate_by_name=True`
`min_items` / `max_items`	`min_length` / `max_length` (list)
`regex=`	`pattern=`
`.copy()`	`.model_copy()`
`.parse_file(p)`	(제거됨) `.model_validate_json(open(p).read())`

성능 팁

Rust 코어: v2 는 파싱/직렬화 대부분이 Rust. 벤치마크 v1 대비 5-50배.
model_dump(mode='json'): dict 대신 JSON 호환 dict 반환 (datetime, UUID 등 문자열).
model_dump_json(): dict 를 거치지 않고 바로 JSON 직렬화. 가장 빠름.
큰 리스트 응답: response_model 이 성능 병목이 될 수 있음. 필요 시 response_model=None + 직접 dict 반환.

함정

[!WARNING] v1 API 를 v2 에서 쓰면 deprecation warning + eventually 오류. 프로젝트 시작 시 반드시 v2 로.

[!CAUTION] from_attributes=True (ORM 모드) 없이 SQLAlchemy 객체를 반환하면 응답 직렬화 실패. Response model 을 쓰면 반드시 이 설정.

[!WARNING] JSON Schema 순환 참조. Forward reference (list["User"]) 는 v2 에서 자동 해결되지만, 매우 깊은 중첩은 model_rebuild() 필요.

[!IMPORTANT] Field(default=...) vs Field(default_factory=...). Mutable 기본값 (list, dict) 는 반드시 default_factory 사용. default=[] 는 모든 인스턴스가 공유하는 위험한 mutable default.

[!CAUTION] Literal 파싱. Literal["a", "b"] 는 정확한 문자열만 허용, case-sensitive. 대소문자 무관하게 하려면 field_validator 로 lower/upper 변환.

[FastAPI] Routing (Path Operations)

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI Routing 은 HTTP method + URL 을 Python 함수 (path operation) 에 매핑하는 시스템입니다. Starlette 의 라우팅 위에 type hint 기반 파라미터 파싱, 자동 검증, 문서화, 응답 직렬화 를 얹었습니다.

기본 데코레이터

@app.get("/items/")
@app.post("/items/")
@app.put("/items/{id}")
@app.patch("/items/{id}")
@app.delete("/items/{id}")
@app.head("/items/{id}")
@app.options("/items/")
@app.trace("/items/")

각 데코레이터의 인자:

@app.get(
    "/items/{id}",
    response_model=Item,             # 응답 스키마
    status_code=200,
    tags=["items"],
    summary="아이템 조회",
    description="ID 로 아이템을 가져옵니다.",
    response_description="아이템 상세",
    responses={
        404: {"description": "Not Found"},
    },
    deprecated=False,
    include_in_schema=True,
)

Path Parameter

경로에 중괄호 {name} 로 선언, 함수 인자로 받음.

@app.get("/users/{user_id}")
def get_user(user_id: int):    # int 로 자동 파싱 + 검증
    return {"id": user_id}

user_id: int 이므로 /users/abc 는 자동으로 422 (Unprocessable Entity) 반환.

Path 순서

경로 매칭은 선언 순서 로 수행. 더 구체적인 경로를 먼저:

@app.get("/users/me")           # 이 순서로 선언
def get_current_user():
    ...

@app.get("/users/{user_id}")    # {user_id} = "me" 로 잡히지 않도록
def get_user(user_id: int):
    ...

경로 컨버터

Starlette 의 컨버터 사용:

@app.get("/files/{file_path:path}")   # 슬래시 포함
def read_file(file_path: str):
    return {"file_path": file_path}

:path 는 나머지 전체를 매칭. /files/home/user/x.txt 에서 file_path = "home/user/x.txt".

Enum 컨버터

from enum import Enum

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

@app.get("/models/{name}")
def get_model(name: ModelName):
    ...

값이 enum 에 없으면 422 반환.

Query Parameter

함수 인자 중 path 에 없는 것 은 자동으로 query.

@app.get("/items/")
def list_items(
    skip: int = 0,
    limit: int = 10,
    q: str | None = None,
):
    ...

기본값 있으면 optional, 없으면 required.

Query 클래스로 상세 지정

from fastapi import Query

@app.get("/items/")
def list_items(
    q: str | None = Query(
        None,
        min_length=3,
        max_length=50,
        pattern=r"^[a-zA-Z0-9]+$",
        title="Query string",
        description="검색어",
        alias="search",             # 실제 query key = search
        deprecated=False,
        include_in_schema=True,
    )
):
    return {"q": q}

List query parameter

@app.get("/items/")
def list_items(tags: list[str] = Query([])):
    return {"tags": tags}

URL: /items/?tags=a&tags=b&tags=c -> tags=["a","b","c"].

Request Body

Pydantic BaseModel 로 선언.

from pydantic import BaseModel

class ItemCreate(BaseModel):
    name: str
    price: float
    tax: float | None = None

@app.post("/items/")
def create_item(item: ItemCreate):
    return item

Body 는 JSON 파싱 후 Pydantic 검증. 실패 시 422.

여러 body 파라미터

class User(BaseModel): ...
class Item(BaseModel): ...

@app.post("/items/")
def create_item(user: User, item: Item):
    ...

Body 는 {"user": {...}, "item": {...}} 형태.

단일 필드 body: Body() 로 명시:

from fastapi import Body

@app.post("/items/")
def create_item(importance: int = Body(...)):
    ...

Form 데이터

from fastapi import Form

@app.post("/login/")
def login(username: str = Form(...), password: str = Form(...)):
    ...

multipart/form-data 를 파싱하려면 python-multipart 설치 필요.

파일 업로드

from fastapi import File, UploadFile

@app.post("/uploadfile/")
def upload_file(file: UploadFile = File(...)):
    return {"filename": file.filename, "content_type": file.content_type}

UploadFile 은 SpooledTemporaryFile (메모리 소량 후 디스크). 큰 파일에 유리.

여러 파일:

@app.post("/uploadfiles/")
def upload_files(files: list[UploadFile] = File(...)):
    return {"filenames": [f.filename for f in files]}

from fastapi import Header, Cookie

@app.get("/items/")
def read_items(
    user_agent: str | None = Header(None),
    x_token: str = Header(...),
    session_id: str | None = Cookie(None),
):
    ...

Header 이름은 자동으로 _ -> - 변환. user_agent -> User-Agent.

Response Model

response_model 은 응답 스키마 + 필터링.

class UserIn(BaseModel):
    username: str
    password: str  # 요청에만
    email: str

class UserOut(BaseModel):
    username: str
    email: str

@app.post("/users/", response_model=UserOut)
def create_user(user: UserIn):
    return user   # password 필드는 자동으로 응답에서 제거

response_model_exclude / include

@app.get(
    "/items/{id}",
    response_model=Item,
    response_model_exclude={"password", "internal_field"},
)

response_model_exclude_unset / _none / _defaults

exclude_unset=True: 요청에 명시된 필드만 응답
exclude_none=True: None 값 필드 제거
exclude_defaults=True: 기본값과 같은 필드 제거

Status Code

from fastapi import status

@app.post("/items/", status_code=status.HTTP_201_CREATED)
def create_item(item: Item):
    ...

@app.delete("/items/{id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_item(id: int):
    ...   # 204 는 body 없음, return 값 무시

APIRouter

여러 endpoint 를 모듈로 분할.

# routers/users.py
from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/users",
    tags=["users"],
    dependencies=[Depends(verify_token)],   # 라우터 전체에 DI 적용
    responses={404: {"description": "Not found"}},
)

@router.get("/{id}")
def read_user(id: int):
    ...

@router.post("/")
def create_user(user: UserCreate):
    ...

# main.py
from fastapi import FastAPI
from myapp.routers import users, items

app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/api/v1")

응답 변형

JSONResponse (기본)

from fastapi.responses import JSONResponse

@app.get("/items/{id}")
def read_item(id: int):
    return JSONResponse({"id": id}, status_code=200)

HTMLResponse, PlainTextResponse

from fastapi.responses import HTMLResponse

@app.get("/", response_class=HTMLResponse)
def read_root():
    return "<h1>Hello</h1>"

StreamingResponse

from fastapi.responses import StreamingResponse

@app.get("/large-file")
def large_file():
    def iterfile():
        with open("/path/to/large.bin", "rb") as f:
            yield from f
    return StreamingResponse(iterfile(), media_type="application/octet-stream")

FileResponse

from fastapi.responses import FileResponse

@app.get("/download")
def download():
    return FileResponse("/path/to/file.pdf", filename="report.pdf")

RedirectResponse

from fastapi.responses import RedirectResponse

@app.get("/old")
def old_endpoint():
    return RedirectResponse("/new")

Response Headers

from fastapi import Response

@app.get("/items/{id}")
def read_item(id: int, response: Response):
    response.headers["X-Custom"] = "value"
    response.set_cookie(key="session", value="abc")
    return {"id": id}

Path Operation 데코레이터 순서

여러 데코레이터를 겹치면 아래부터 위 순서로 적용:

@app.get("/items/", tags=["items"])
@some_other_decorator     # 데코레이터 순서 주의
def read_items():
    ...

FastAPI 데코레이터는 라우팅에 대한 등록이므로 다른 데코레이터 (예: 캐시) 는 그 아래에 위치해야 등록에 적용됨.

OpenAPI 커스터마이제이션

from fastapi.openapi.utils import get_openapi

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title="My API",
        version="1.0.0",
        description="...",
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://.../logo.png"}
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi

함정

[!WARNING] Path 순서. /users/{id} 가 /users/me 보다 먼저 선언되면 /users/me 가 id=me 로 파싱되어 422.

[!CAUTION] Trailing slash. FastAPI 는 /items 와 /items/ 를 다른 경로로 취급. Starlette 의 redirect_slashes=True (기본) 로 307 리디렉트되지만, 프로덕션에서는 명시적으로 하나만 사용.

[!WARNING] response_model 과 return type hint 는 다를 수 있음. return type hint 는 Python 검사용, response_model 은 FastAPI 필터/문서화용. 일관되게 유지하려면 둘 다 지정.

[!IMPORTANT] include_router 의 prefix 는 라우터 자체 prefix 와 결합. router = APIRouter(prefix="/users") 에 app.include_router(router, prefix="/api/v1") 하면 최종 /api/v1/users/....

[!CAUTION] Path parameter 이름 중복 되면 뒤의 것이 앞을 덮음 (Python 함수 인자 규칙). 다른 이름 사용.

[FastAPI] Testing

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI Testing 은 endpoint 를 실제 서버 없이 직접 호출해 응답을 검증하는 workflow 입니다. Starlette 의 TestClient (내부적으로 httpx sync) 또는 httpx.AsyncClient 로 앱 인스턴스를 감쌉니다.

TestClient 기본

from fastapi import FastAPI
from fastapi.testclient import TestClient

app = FastAPI()

@app.get("/hello")
def hello():
    return {"msg": "world"}

client = TestClient(app)

def test_hello():
    resp = client.get("/hello")
    assert resp.status_code == 200
    assert resp.json() == {"msg": "world"}

TestClient 는 프로세스 내부에서 ASGI 앱을 직접 호출. HTTP 서버 미기동. 매우 빠름.

pytest 통합

# conftest.py
import pytest
from fastapi.testclient import TestClient
from myapp.main import app

@pytest.fixture
def client():
    with TestClient(app) as c:
        yield c

# test_users.py
def test_read_user(client):
    resp = client.get("/users/1")
    assert resp.status_code == 200

def test_create_user(client):
    resp = client.post("/users/", json={"email": "a@b.com", "password": "secret123"})
    assert resp.status_code == 201
    data = resp.json()
    assert data["email"] == "a@b.com"

Async 테스트 (httpx.AsyncClient)

TestClient 는 sync. Async endpoint 를 async 스타일로 테스트하려면 httpx.AsyncClient.

import pytest
import httpx
from httpx import ASGITransport
from myapp.main import app

@pytest.mark.asyncio
async def test_read_user_async():
    async with httpx.AsyncClient(
        transport=ASGITransport(app=app),
        base_url="http://test",
    ) as ac:
        resp = await ac.get("/users/1")
        assert resp.status_code == 200

pytest-asyncio 필요. asyncio_mode = "auto" 로 설정하면 @pytest.mark.asyncio 생략 가능.

# pyproject.toml
[tool.pytest.ini_options]
asyncio_mode = "auto"

dependency_overrides (핵심)

Endpoint 코드를 안 바꾸고 dependency 를 mock. 테스트 인프라의 심장.

from fastapi import Depends
from sqlalchemy.orm import Session

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

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

테스트:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

TEST_DB_URL = "sqlite:///./test.db"
engine = create_engine(TEST_DB_URL, connect_args={"check_same_thread": False})
TestSessionLocal = sessionmaker(bind=engine)

def override_get_db():
    db = TestSessionLocal()
    try: yield db
    finally: db.close()

@pytest.fixture(autouse=True)
def setup_db():
    Base.metadata.create_all(engine)
    app.dependency_overrides[get_db] = override_get_db
    yield
    Base.metadata.drop_all(engine)
    app.dependency_overrides = {}

autouse=True 로 모든 테스트에 자동 적용. 테스트 후 override clear.

DB 테스트 패턴

패턴 1: SQLite in-memory

engine = create_engine("sqlite:///:memory:", connect_args={"check_same_thread": False})

Pros: 매우 빠름, 격리 완벽
Cons: PostgreSQL 특화 기능 (JSONB, LATERAL, …) 없음

패턴 2: Docker Postgres + fresh DB per test

@pytest.fixture(scope="session")
def db_engine():
    engine = create_engine("postgresql://test:test@localhost/testdb")
    yield engine

@pytest.fixture(scope="function")
def db_session(db_engine):
    connection = db_engine.connect()
    transaction = connection.begin()
    Session = sessionmaker(bind=connection)
    session = Session()
    yield session
    session.close()
    transaction.rollback()   # 테스트 후 롤백
    connection.close()

Pros: 프로덕션 DB 와 동일. Transaction rollback 으로 격리. Cons: Docker 필요, 느림.

패턴 3: testcontainers

from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="session")
def postgres():
    with PostgresContainer("postgres:16") as p:
        yield p.get_connection_url()

Auth 테스트

@pytest.fixture
def authed_client():
    def override_current_user():
        return User(id=1, email="test@example.com", is_admin=True)

    app.dependency_overrides[get_current_user] = override_current_user

    with TestClient(app) as c:
        yield c

    app.dependency_overrides = {}

또는 실제 토큰 발급 후 헤더 전달:

@pytest.fixture
def token():
    return create_access_token({"sub": "user@example.com"})

def test_protected(client, token):
    resp = client.get("/me", headers={"Authorization": f"Bearer {token}"})
    assert resp.status_code == 200

파일 업로드 테스트

def test_upload(client):
    with open("tests/fixtures/sample.pdf", "rb") as f:
        resp = client.post(
            "/upload",
            files={"file": ("sample.pdf", f, "application/pdf")},
        )
    assert resp.status_code == 200

WebSocket 테스트

def test_websocket():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "echo: hello"

Startup / Shutdown 이벤트

TestClient context manager (with TestClient(app) as c) 는 lifespan 이벤트를 실행.

@asynccontextmanager
async def lifespan(app: FastAPI):
    print("startup")
    yield
    print("shutdown")

app = FastAPI(lifespan=lifespan)

def test_lifespan():
    with TestClient(app) as client:
        client.get("/")   # startup 이미 실행
    # exit 시 shutdown

외부 API mocking (httpx)

httpx.AsyncClient 를 httpx_mock 또는 respx 로 mock.

import respx
from httpx import Response

@respx.mock
def test_external_call(client):
    respx.get("https://api.example.com/data").mock(
        return_value=Response(200, json={"key": "value"})
    )
    resp = client.get("/wrapped")
    assert resp.json()["proxied"] == "value"

Test isolation

각 테스트는 격리되어야 함. 안 지키면 flaky.

DB: transaction rollback 또는 truncate
Cache (Redis): FLUSHDB 또는 db=1
File system: tmp_path fixture
Global state: 반드시 avoidance (dependency injection 사용)

성능 테스트

로컬 부하 테스트:

pip install locust
locust -f locustfile.py --host http://localhost:8000

from locust import HttpUser, task

class WebsiteUser(HttpUser):
    @task
    def get_items(self):
        self.client.get("/items/")

    @task(3)   # 3배 자주
    def get_root(self):
        self.client.get("/")

Coverage

pytest --cov=myapp --cov-report=html --cov-report=term-missing

.coveragerc 로 branch coverage 등 세부 설정.

함정

[!WARNING] TestClient 안에서 request body 를 pydantic 검증하는 실제 endpoint 를 호출. Sync/async 미스매치 조심.

[!CAUTION] dependency_overrides clear 안 하면 다음 테스트로 leak. autouse=True fixture 로 자동 cleanup.

[!WARNING] DB session 을 fixture 로 재사용 시 lazy load 실패. SQLAlchemy 는 session close 후 relationship 접근 불가. expire_on_commit=False 또는 explicit refresh.

[!IMPORTANT] TestClient(app) 은 lifespan 을 실행하지 않는 사용 방식이 있음. with TestClient(app) as c 형태로 반드시 사용.

[!CAUTION] AsyncClient(transport=ASGITransport(app=app)) 처럼 명시적 transport 지정. base_url 도 정확히.

[FastAPI] WebSockets

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI WebSockets 는 Starlette 위에서 양방향 실시간 통신을 제공합니다. HTTP 대신 ws:// / wss:// 스킴을 쓰며, 한 연결 위에서 서버와 클라이언트가 자유롭게 메시지를 주고받습니다.

주요 용도: 채팅, 실시간 알림, 라이브 대시보드, 게임, 협업 편집.

기본 사용

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"echo: {data}")

accept(): 핸드셰이크 완료, 연결 활성화
receive_text() / receive_bytes() / receive_json(): 메시지 수신 (blocking, coroutine)
send_text() / send_bytes() / send_json(): 송신

연결 종료 처리

from fastapi import WebSocketDisconnect

@app.websocket("/ws")
async def ws_ep(websocket: WebSocket):
    await websocket.accept()
    try:
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"got: {data}")
    except WebSocketDisconnect:
        print("client disconnected")

클라이언트 종료 -> WebSocketDisconnect 예외. 반드시 catch 하고 자원 정리.

WebSocket 은 브라우저 API 상 커스텀 헤더를 못 붙임 (subprotocol 은 가능). 대개 query 나 cookie 로 토큰 전달.

Query 파라미터

from fastapi import Query, WebSocketException, status

@app.websocket("/ws")
async def ws_ep(
    websocket: WebSocket,
    token: str = Query(...),
):
    user = validate_token(token)
    if not user:
        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
    await websocket.accept()
    ...

@app.websocket("/ws")
async def ws_ep(
    websocket: WebSocket,
    session: str | None = Cookie(default=None),
    x_client_id: str | None = Header(default=None),
):
    ...

주의: WebSocket dependency 는 Depends() 도 지원하지만 HTTPException 대신 WebSocketException 을 사용해야 합니다.

Dependency Injection

async def get_current_user_ws(token: str = Query(...)) -> User:
    user = validate_token(token)
    if not user:
        raise WebSocketException(code=status.WS_1008_POLICY_VIOLATION)
    return user

@app.websocket("/ws")
async def ws_ep(
    websocket: WebSocket,
    user: Annotated[User, Depends(get_current_user_ws)],
    db: Annotated[AsyncSession, Depends(get_async_db)],
):
    await websocket.accept()
    ...

Broadcast 패턴

여러 클라이언트에 같은 메시지 전송.

단순 in-memory manager

class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            try:
                await ws.send_text(message)
            except Exception:
                pass   # 연결 끊긴 클라이언트

manager = ConnectionManager()

@app.websocket("/chat/{room}")
async def chat(websocket: WebSocket, room: str):
    await manager.connect(websocket)
    try:
        while True:
            data = await websocket.receive_text()
            await manager.broadcast(f"[{room}] {data}")
    except WebSocketDisconnect:
        manager.disconnect(websocket)
        await manager.broadcast(f"[{room}] user left")

제한: 단일 프로세스. 여러 워커면 프로세스 간 broadcast 안 됨.

다중 프로세스 broadcast (Redis pub/sub)

import redis.asyncio as redis
import asyncio, json

class BroadcastManager:
    def __init__(self, url: str):
        self.pub = redis.from_url(url)
        self.sub = redis.from_url(url)
        self.local_conns: set[WebSocket] = set()

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.local_conns.add(ws)

    def disconnect(self, ws: WebSocket):
        self.local_conns.discard(ws)

    async def publish(self, channel: str, message: dict):
        await self.pub.publish(channel, json.dumps(message))

    async def subscribe(self, channel: str):
        pubsub = self.sub.pubsub()
        await pubsub.subscribe(channel)
        async for msg in pubsub.listen():
            if msg["type"] != "message":
                continue
            data = json.loads(msg["data"])
            for ws in list(self.local_conns):
                try:
                    await ws.send_json(data)
                except Exception:
                    self.local_conns.discard(ws)

manager = BroadcastManager("redis://localhost")

@asynccontextmanager
async def lifespan(app: FastAPI):
    task = asyncio.create_task(manager.subscribe("chat"))
    yield
    task.cancel()

app = FastAPI(lifespan=lifespan)

또는 broadcaster 패키지 (encode.io) 로 Redis/Postgres/Memory backend 통합.

Subprotocol

클라이언트가 원하는 서브프로토콜을 협상 (예: MQTT over WebSocket, GraphQL Subscriptions).

@app.websocket("/ws")
async def ws_ep(websocket: WebSocket):
    proto = websocket.headers.get("sec-websocket-protocol", "")
    if "myproto.v1" in proto:
        await websocket.accept(subprotocol="myproto.v1")
    else:
        await websocket.close(code=1002)
        return

클라이언트 예시

const ws = new WebSocket("wss://api.example.com/ws?token=abc");
ws.onopen = () => console.log("open");
ws.onmessage = (e) => console.log("msg:", e.data);
ws.onclose = () => console.log("closed");
ws.send("hello");

Python 클라이언트 (테스트용):

import asyncio
import websockets

async def client():
    async with websockets.connect("ws://localhost:8000/ws?token=abc") as ws:
        await ws.send("hello")
        print(await ws.recv())

asyncio.run(client())

Heartbeat / Ping-Pong

Idle 연결을 감지하려면 주기적 ping.

@app.websocket("/ws")
async def ws_ep(websocket: WebSocket):
    await websocket.accept()
    async def sender():
        while True:
            await asyncio.sleep(30)
            try:
                await websocket.send_json({"type": "ping"})
            except Exception:
                return

    async def receiver():
        while True:
            data = await websocket.receive_json()
            if data.get("type") == "pong":
                continue
            # handle real message

    await asyncio.gather(sender(), receiver())

Nginx / ALB / CloudFront 앞단이 있으면 idle timeout 을 유의 (기본 60초).

테스트

TestClient.websocket_connect 는 context manager:

from fastapi.testclient import TestClient

def test_websocket():
    client = TestClient(app)
    with client.websocket_connect("/ws?token=valid") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "got: hello"

배포 시 유의점

Uvicorn workers

uvicorn main:app --workers 4

WebSocket 은 프로세스 로컬 상태. 다중 워커 broadcast 필요 시 Redis pub/sub.

프록시 (nginx, ALB, CloudFront)

Upgrade / Connection 헤더 통과 필수 (proxy_set_header Upgrade $http_upgrade)
Idle timeout 확대 (예: nginx proxy_read_timeout 3600)
CloudFront: WebSocket 지원, 별도 설정 없음
ALB: WebSocket 지원, target group 의 stickiness 고려

Kubernetes

Service type: ClusterIP + Ingress (Nginx ingress 는 annotation 필요)
Session affinity: 필요 시 Ingress 에서 sticky session

SSE (Server-Sent Events) 와 비교

축	WebSocket	SSE
방향	양방향	서버 -> 클라이언트만
프로토콜	ws/wss	HTTP text/event-stream
재연결	수동	자동 (`retry`)
바이너리	지원	텍스트만
프록시 호환성	별도 설정 필요	표준 HTTP
적합	채팅, 게임, 협업	로그 스트림, 알림

Client-only push 라면 SSE 가 더 단순하고 안정적.

함정

[!WARNING] WebSocket 은 인증을 처음에만. 세션 만료를 감지하려면 앱 레벨 재검증 (예: 5분마다 서버가 token refresh 요구).

[!CAUTION] In-memory manager 는 프로세스 한 개용. 다중 워커 + broadcast 는 반드시 Redis / Postgres pub/sub.

[!WARNING] 연결 dangling. 클라이언트가 조용히 사라지면 서버가 오래 알아채지 못함. Heartbeat + idle timeout 필수.

[!IMPORTANT] 응답 스키마 없음. WebSocket 은 OpenAPI 스키마화가 제한적. AsyncAPI 등 별도 문서화.

[!CAUTION] Backpressure. 클라이언트가 느리면 서버 send buffer 가 쌓임. send 가 대기 상태로. 큐 사이즈 제한 + drop policy 설계.

[Python] FastAPI

koa (김신건) — Tue, 07 Jul 2026 00:00:00 GMT

정의

FastAPI 는 Python 3.8+ 을 위한 ASGI 기반 현대 웹/API 프레임워크 입니다. Sebastián Ramírez (tiangolo) 가 2018년 발표했고, 세 가지 축을 결합해 폭발적으로 성장했습니다.

Starlette: ASGI 프레임워크 (라우팅, 미들웨어, WebSocket)
Pydantic: 타입 힌트 기반 데이터 검증 + 직렬화
Uvicorn / Hypercorn: ASGI 서버 (uvloop + httptools)

왜 FastAPI 인가

1. Type hint = spec

Python 타입 힌트를 그대로 요청 검증, 응답 직렬화, OpenAPI 스키마 생성에 활용. 별도 스키마 정의 파일이 없습니다.

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    price: float
    tax: float | None = None

@app.post("/items/")
def create_item(item: Item) -> Item:
    return item

이 한 함수가 자동으로:

요청 body 검증 (name 은 str, price 는 float)
응답 직렬화 + response_model 검증
OpenAPI/Swagger UI (/docs) + ReDoc (/redoc) 자동 생성
IDE 자동완성 지원

2. 성능

Uvicorn (uvloop) + Starlette 조합으로 Node.js/Go 급 처리량. Python 웹 프레임워크 중 최상급 벤치마크.

3. 개발자 경험

자동 문서화 (Swagger, ReDoc)
IDE 지원 완벽 (mypy, pylance)
학습 곡선 완만 (Flask 스타일 데코레이터)

4. 표준 준수

OpenAPI 3.0/3.1, JSON Schema, OAuth2, JWT 표준 그대로. 별도 커스텀 스펙 없음.

아키텍처

┌─────────────────┐
│  Uvicorn (ASGI) │  ← HTTP + WebSocket
└────────┬────────┘
         ↓
┌─────────────────┐
│    FastAPI      │  ← 라우팅 데코레이터, DI, response_model
└────────┬────────┘
         ↓
┌─────────────────┐
│    Starlette    │  ← Routing, Middleware, Request/Response, WS
└────────┬────────┘
         ↓
┌─────────────────┐
│    Pydantic     │  ← Validation, Serialization
└─────────────────┘

Hello World

pip install fastapi uvicorn[standard]

# main.py
from fastapi import FastAPI

app = FastAPI(title="My API", version="1.0.0")

@app.get("/")
def read_root():
    return {"hello": "world"}

@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

uvicorn main:app --reload
# http://localhost:8000
# http://localhost:8000/docs   ← Swagger UI
# http://localhost:8000/redoc  ← ReDoc

핵심 개념

Path Operation

라우팅 데코레이터 = “path operation”. HTTP method + URL 을 함수에 연결.

@app.get("/items/")        # 조회
@app.post("/items/")       # 생성
@app.put("/items/{id}")    # 전체 갱신
@app.patch("/items/{id}")  # 부분 갱신
@app.delete("/items/{id}") # 삭제

자세한 것은 [[fastapi-routing|FastAPI Routing]] 참조.

Pydantic 모델

요청 body, 응답 스키마를 Pydantic BaseModel 로 정의. v2 는 Rust 코어로 v1 대비 5-50배 빠름.

from pydantic import BaseModel, Field

class UserCreate(BaseModel):
    email: str = Field(..., description="이메일")
    password: str = Field(..., min_length=8)

class UserOut(BaseModel):
    id: int
    email: str

자세한 것은 [[fastapi-pydantic|FastAPI + Pydantic]] 참조.

Dependency Injection

Depends() 로 DB 세션, 인증 사용자, 설정 등 주입. FastAPI 의 핵심 매력.

from fastapi import Depends

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

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

자세한 것은 [[fastapi-dependency-injection|FastAPI Dependency Injection]] 참조.

Async vs Sync

@app.get("/sync")
def sync_endpoint():           # 스레드풀에서 실행
    return blocking_call()

@app.get("/async")
async def async_endpoint():    # 이벤트 루프에서 실행
    return await async_call()

함정: def 안에서 await 없이 sleep 하면 스레드풀 워커 하나 소비. async def 안에서 time.sleep 하면 이벤트 루프 전체가 멈춤. 자세한 것은 [[fastapi-async|FastAPI Async]] 참조.

기본 프로젝트 구조

myapp/
├── src/
│   └── myapp/
│       ├── __init__.py
│       ├── main.py            # FastAPI 인스턴스, 라우터 include
│       ├── config.py          # Settings (pydantic-settings)
│       ├── database.py        # SQLAlchemy engine, session
│       ├── deps.py            # 공통 Depends
│       ├── models.py          # SQLAlchemy models
│       ├── schemas.py         # Pydantic models
│       ├── routers/
│       │   ├── __init__.py
│       │   ├── users.py       # APIRouter
│       │   └── items.py
│       └── security.py        # OAuth2, JWT
├── tests/
│   └── test_users.py
├── pyproject.toml
└── Dockerfile

APIRouter 로 라우트 분할

# routers/users.py
from fastapi import APIRouter

router = APIRouter(prefix="/users", tags=["users"])

@router.get("/{id}")
def read_user(id: int):
    ...

# main.py
from myapp.routers import users, items

app = FastAPI()
app.include_router(users.router)
app.include_router(items.router)

OpenAPI 자동화

FastAPI 는 모든 path operation 을 스캔해 OpenAPI 3.1 스펙 자동 생성:

/openapi.json: OpenAPI 스펙
/docs: Swagger UI (인터랙티브 테스트)
/redoc: ReDoc (읽기용 문서)

프로덕션에서 문서 UI 를 감추려면:

app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

주요 확장 도구

도구	역할
SQLAlchemy 2.0	ORM (async 지원)
SQLModel	Pydantic + SQLAlchemy 통합 (tiangolo 제작)
Alembic	DB 마이그레이션
pydantic-settings	환경변수 기반 설정
Celery / Arq / RQ	태스크 큐
Redis	캐시, pub/sub
httpx	비동기 HTTP 클라이언트 (테스트에도)
Sentry / OpenTelemetry	관측

배포 개요

FROM python:3.12-slim
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN pip install uv && uv sync --no-dev
COPY src /app/src
CMD ["uvicorn", "myapp.main:app", "--host", "0.0.0.0", "--port", "8000"]

프로덕션은 대개:

Gunicorn + Uvicorn workers: 프로세스 수 = CPU, 각 프로세스 = Uvicorn worker
또는 Uvicorn 다중 프로세스 (--workers N)
또는 Kubernetes + HorizontalPodAutoscaler

자세한 것은 [[fastapi-deployment|FastAPI Deployment]] 참조.

최근 (2025-2026) 변화

FastAPI 0.115+: Query, Form, Body 파라미터를 Pydantic 모델로 그룹핑 가능
Pydantic v2 완전 이행: v1 지원 종료
AsyncGenerator lifespan: @app.on_event("startup") deprecated -> lifespan context manager
response_model_by_alias=False 기본 변경: 응답 필드 alias 처리 변경

함정

[!WARNING] async def 안에서 blocking I/O (파일 읽기, time.sleep, requests) 를 호출하지 마세요. 이벤트 루프가 멈추면서 모든 요청이 대기. run_in_threadpool 사용.

[!CAUTION] Depends 인자를 함수 기본값 자리 밖에 두면 안 됨. Python 함수 시그니처 규칙에 정확히 맞아야 FastAPI 가 DI 로 인식.

[!WARNING] Pydantic v1 → v2 마이그레이션은 breaking change 다수. parse_obj_as, .dict(), Config 등 이름이 바뀜. 프로젝트 시작 시 v2 로 통일.

[!IMPORTANT] response_model 은 성능 비용이 있습니다. 매 응답을 검증 + 직렬화. 응답 크기가 크고 신뢰할 만한 내부 API 라면 생략 고려 (대신 문서 정확도 손실).

김신건의 로그 - 위키 / fastapi

[FastAPI] Async / Sync Endpoints

정의

async def vs def

결정 트리

잘못된 조합의 위험

위험 1: async def 안의 blocking I/O

위험 2: def 안의 async 코드

올바른 조합

run_in_threadpool 브릿지

스레드풀 크기

Dependency 도 async / sync

Async DB (SQLAlchemy 2.0)

Async HTTP client (httpx)

asyncio.gather 로 병렬 요청

CPU-bound 처리

AnyIO 를 통한 크로스 백엔드

언제 어느 것을?

성능 벤치마크 감

함정

관련 위키

[FastAPI] Background Tasks

정의

BackgroundTasks (in-process)

async / sync 모두 지원

Dependency 와 조합

BackgroundTasks 의 한계

외부 Task Queue

Celery (전통적)

Arq (async 지향)

RQ (Redis Queue)

Dramatiq

큐 선택 가이드

실시간 진행 상황

Idempotency

함정

관련 위키

[FastAPI] Dependency Injection

정의

기본 사용

Type hint 지원

Class-based Dependency

Sub-dependency

Cache 비활성화

Yield-based (Cleanup)

Async yield

Router / App level dependency

인증 (OAuth2 / JWT 예시)

dependency_overrides (테스트)

Global State Anti-pattern

서비스 계층 DI

Depends() 실행 순서

Background Task 와 DI

함정

관련 위키

[FastAPI] Deployment (Uvicorn, Gunicorn, Docker)

정의

구성 계층

Uvicorn 단독 (개발/간단 프로덕션)

Uvicorn —workers vs Gunicorn

Gunicorn + Uvicorn worker

UvicornWorker vs UvicornH11Worker

Worker 수 결정

신호 처리 & graceful shutdown

Docker

최소 Dockerfile

Multi-stage build (이미지 크기 최소화)

이미지 스택 선택

Kubernetes 배포

Probe 엔드포인트

Reverse Proxy 설정

Nginx

AWS ALB

로깅 & 관측

구조화 로그

OpenTelemetry

Sentry

환경 변수 & Secrets

성능 팁

함정

위험 1: `async def` 안의 blocking I/O

위험 2: `def` 안의 async 코드