🧱 Middleware – 요청과 응답을 설계하는 핵심 지점

FastAPI에서 Middleware는 요청(Request)과 응답(Response)의 흐름을 통제하는 설계 지점이다.

인증, 로깅, 성능 측정, 보안, 요청 차단처럼
모든 요청에 공통으로 적용되는 규칙은 전부 미들웨어 계층에서 처리된다.

🤔 Middleware 란?

Middleware는 요청(Request)과 응답(Response) 사이에 위치한 코드다.

클라이언트가 요청을 보내면

• 요청이 먼저 Middleware를 거치고
• 그 다음 Path Operation(라우트 함수)로 들어가며
• 응답이 나갈 때 다시 Middleware를 거친다

👉 요청 시 한 번, 응답 시 한 번
👉 항상 두 번 실행된다

🚪 비유로 이해하기

Middleware는 건물 입구의 보안 검색대와 같다.

• 들어올 때 검사한다
• 나갈 때 기록한다

누가 들어왔는지,들어와도 되는지, 얼마나 오래 머물렀는지를
비즈니스 로직에 들어가기 전에 판단한다.

🔁 Middleware 동작 흐름

요청 / 응답 흐름 요약

Client
  ↓
Middleware (요청 전 처리)
  ↓
call_next(request)
  ↓
Path Operation (비즈니스 로직)
  ↓
Middleware (응답 후 처리)
  ↓
Client

Middleware는 요청을 가로채고, 다시 되돌려 받는 구조를 가진다.

🧠 Middleware 함수 구조

모든 Middleware는 아래와 같은 구조를 가진다.

@app.middleware("http")
async def middleware(request: Request, call_next):
    # 요청 전 처리 (Request 단계)
    response = await call_next(request)
    # 응답 후 처리 (Response 단계)
    return response

🚫 Middleware에서 가능한 것

• 인증 실패 시 요청 차단
• 특정 헤더 없으면 즉시 403 반환
• 로깅만 수행하고 요청 통과

❗ Middleware는 단순한 헬퍼가 아니다
“이 요청을 서버 안으로 들일지 말지”를 결정하는 계층이다

🧱 여러 Middleware가 있을 때

Middleware는 스택(Stack) 구조로 쌓인다.
나중에 등록한 Middleware가 가장 바깥쪽에 위치한다.

요청 흐름
Client
  ↓
Middleware C (인증)
  ↓
Middleware B (시간 측정)
  ↓
Middleware A (로깅)
  ↓
Route

응답 흐름
Route
  ↓
Middleware A
  ↓
Middleware B
  ↓
Middleware C
  ↓
Client

LIFO 구조를 따른다.

---

🏗️ 설계 관점에서의 Middleware

• 모든 요청에 공통으로 적용되는가?
• 비즈니스 로직과 분리 가능한가?
• 요청을 차단할 책임이 있는가?

👉 위 질문에 “예”라면
Middleware로 분리하는 것이 맞다

🧪 실전 예제

이제 Middleware의 개념과 흐름을 이해했으니,
실제로 여러 개의 미들웨어가 어떻게 쌓이고 실행되는지를 확인해보자.

🧱 미들웨어 3개 등록하기

아래 예제에서는 역할이 서로 다른 미들웨어 3개를 등록한다.

• Middleware A → 요청/응답 로깅
• Middleware B → 처리 시간 측정
• Middleware C → 인증 검사

다시 한 번 강조
나중에 등록한 미들웨어가 가장 바깥쪽에 위치한다.

import time
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

# 1️⃣ 가장 안쪽 (가장 마지막에 실행)
@app.middleware("http")
async def middleware_a(request: Request, call_next):
    print("[A] 요청 들어옴 - 로깅 시작")
    print(f"[A] 요청 정보: {request.method} {request.url.path}")

    response = await call_next(request)

    print("[A] 응답 나감 - 로깅 완료")
    return response


# 2️⃣ 중간
@app.middleware("http")
async def middleware_b(request: Request, call_next):
    print("[B] 요청 들어옴 - 처리 시간 측정 시작")
    start_time = time.perf_counter()

    response = await call_next(request)

    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = f"{process_time:.4f}"
    print(f"[B] 응답 나감 - 처리 시간: {process_time:.4f}초")
    return response


# 3️⃣ 가장 바깥쪽 (가장 먼저 실행)
@app.middleware("http")
async def middleware_c(request: Request, call_next):
    print("[C] 요청 들어옴 - 인증 검사 시작")

    # 문서 경로는 인증 제외
    if request.url.path in ["/docs", "/openapi.json", "/redoc"]:
        print("[C] 문서 경로는 인증 건너뜀")
        response = await call_next(request)
        print("[C] 응답 나감")
        return response

    auth_token = request.headers.get("X-Auth-Token")
    if request.url.path == "/secret" and not auth_token:
        print("[C] 인증 실패! 요청 거부")
        return JSONResponse(
            status_code=403,
            content={"detail": "X-Auth-Token 헤더가 필요해요"}
        )

    print("[C] 인증 통과")
    response = await call_next(request)
    print("[C] 응답 나감")
    return response


@app.get("/")
def root():
    print("--- [Route] / 실행 ---")
    return {"message": "Hello, jeff!"}


@app.get("/secret")
async def secret():
    print("--- [Route] /secret 실행 ---")
    return {"message": "비밀 데이터예요"}

▶ 실행 결과 로그

서버를 실행하고 http://localhost:8000에 접속하면
터미널에 아래와 같은 로그가 출력된다.

[C] 요청 들어옴 - 인증 검사 시작
[C] 인증 통과
[B] 요청 들어옴 - 처리 시간 측정 시작
[A] 요청 들어옴 - 로깅 시작
[A] 요청 정보: GET /
--- [Route] / 실행 ---
[A] 응답 나감 - 로깅 완료
[B] 응답 나감 - 처리 시간: 0.0028초
[C] 응답 나감

👉 요청 시: C → B → A → Route
👉 응답 시: Route → A → B → C

🧭 실행 흐름 다이어그램

요청 흐름
Client
  ↓
Middleware C (인증)
  ↓
Middleware B (시간 측정)
  ↓
Middleware A (로깅)
  ↓
Route

응답 흐름
Route
  ↓
Middleware A
  ↓
Middleware B
  ↓
Middleware C
  ↓
Client

🔐 간단한 인증 미들웨어

특정 헤더가 없으면 요청을 차단하는 예제

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

app = FastAPI()

@app.middleware("http")
async def check_auth_header(request: Request, call_next):
    # 문서 관련 경로는 인증 제외
    if request.url.path in ["/docs", "/openapi.json", "/redoc"]:
        return await call_next(request)

    auth_token = request.headers.get("X-Auth-Token")

    if not auth_token:
        return JSONResponse(
            status_code=403,
            content={"detail": "X-Auth-Token 헤더가 필요해요"}
        )

    return await call_next(request)

🧾 정리

• Middleware는 스택(Stack) 구조로 실행된다
• 나중에 등록한 미들웨어가 가장 바깥쪽이다
• 요청과 응답의 실행 흐름은 서로 반대다
• 인증·로깅·성능 측정은 Middleware의 책임이다