FastAPI에서 middleware는 어떻게 동작합니까?

Question

Accepted Answer

FastAPI의 **middleware**는 **모든 요청과 응답**에 대해 실행되는 코드로, 엔드포인트를 감싸 로깅, 타이밍, CORS, 헤더 추가 같은 횡단 관심사(cross-cutting concern)를 처리합니다. FastAPI는 Starlette의 middleware 시스템을 사용합니다(ASGI 기반).

## 커스텀 middleware 작성

```python
import time

@app.middleware("http")
async def add_timing(request: Request, call_next):
    start = time.time()
    response = await call_next(request)        # 엔드포인트(및 내부 middleware) 호출
    response.headers["X-Process-Time"] = str(time.time() - start)   # 응답 수정
    return response
```

패턴: `await call_next(request)` 이전의 코드는 **들어오는 방향**(엔드포인트 이전)에 실행되고, `call_next`가 엔드포인트를 호출하며, 이후의 코드는 **나가는 방향**(응답 수정)에 실행됩니다. 이것이 모든 요청을 감쌉니다. 여기서는 모든 응답에 타이밍 헤더를 추가합니다.

## 요청/응답 흐름

```text
요청  → MW1 → MW2 → 엔드포인트
응답  ← MW1 ← MW2 ← 엔드포인트
middleware는 엔드포인트를 감쌉니다; 들어올 때 순서대로, 나갈 때 역순으로 실행됩니다.
```

## 내장 / 일반적인 middleware

```python
from fastapi.middleware.cors import CORSMiddleware
from fastapi.middleware.gzip import GZipMiddleware

app.add_middleware(CORSMiddleware, allow_origins=["https://app.example.com"], ...)  # CORS
app.add_middleware(GZipMiddleware, minimum_size=1000)                               # 압축
```

middleware는 흔히 `add_middleware`로 추가됩니다. CORS(교차 출처 요청 허용), GZip(응답 압축), 신뢰 호스트 검사가 대표적인 내장 middleware입니다.

## 일반적인 middleware 용도

```text
✓ 로깅 / 요청 타이밍 / 메트릭
✓ CORS (교차 출처 요청 처리)
✓ 보안 또는 커스텀 헤더 추가
✓ 응답 압축 (GZip)
✓ Request ID / 상관관계 ID 주입
```

## middleware vs 의존성

```text
middleware   → 모든 요청에 실행; 원시 요청/응답 수준(헤더, 타이밍, 전체 응답)에서 동작.
               진정으로 전역적인 관심사에 최적.
의존성       → 파싱된 매개변수, DI, 타입 지정 값에 접근하는 엔드포인트별(또는 그룹별) 로직.
               인증, validation, 공유 매개변수에 최적.
→ 전역 횡단 관심사에는 middleware를, 엔드포인트 로직에는 의존성을 사용하세요.
```

## 왜 중요한가

middleware는 FastAPI에서 **전역적인 횡단 관심사**—로깅, 요청 타이밍, CORS, 압축, 커스텀 헤더처럼 모든 요청과 응답에 적용되어야 하는 로직—에 적합한 메커니즘입니다.

이를 이해하는 것은 애플리케이션을 올바르게 구조화하는 데 중요합니다: middleware는 모든 엔드포인트를 감싸므로(이전과 이후에 실행되며 요청과 응답을 모두 수정 가능), 모든 엔드포인트에서 반복하면 지루하고 오류가 많을 앱 전역 동작에 이상적입니다.

**middleware**(전역, 원시 요청/응답 수준)와 **의존성**(엔드포인트별, 파싱된/타입 지정 값과 DI 접근 — 인증과 validation에 더 적합) 사이의 구분을 아는 것이 올바른 도구를 선택하는 핵심입니다.

CORS와 압축 같은 일반적인 필요는 내장 middleware로 처리되고, 커스텀 middleware는 로깅과 계측을 다룹니다. 잘 구조화되고 관찰 가능한 API를 구축하기 위한 실용적이고 자주 사용되는 지식입니다.