미들웨어 (Middleware)

미들웨어 (Middleware)

FastAPI 애플리케이션에 **미들웨어(middleware)**를 추가할 수 있어요. 미들웨어는 어떤 특정 경로 동작이 처리되기 전에 모든 요청을, 그리고 모든 응답이 돌아가기 전에 모든 응답을 대상으로 일하는 함수예요. 로그 찍기, 공통 헤더 추가, 측정 같은 반복 작업을 전역에서 한 번에 처리하기에 좋아요.

출처: https://fastapi.tiangolo.com/tutorial/middleware/

본문

미들웨어는 이렇게 동작해요.

  • 애플리케이션에 들어오는 각 요청을 받아요.
  • 그 요청에 뭔가 하거나 필요한 코드를 실행할 수 있어요.
  • 요청을 애플리케이션의 나머지 부분(경로 동작)에 넘겨서 처리하게 해요.
  • 애플리케이션이 만든 응답을 받아요.
  • 그 응답에 뭔가 하거나 필요한 코드를 실행할 수 있어요.
  • 마지막으로 응답을 돌려줘요.

yield가 있는 의존성이 있으면 그 종료 코드는 미들웨어 이후에 실행돼요. 백그라운드 작업이 있다면 모든 미들웨어 이후에 실행돼요.

미들웨어 만들기

미들웨어를 만들려면 함수 위에 @app.middleware("http") 데코레이터를 붙이면 돼요. 그 함수는 두 가지를 받아요.

  • request (요청)
  • call_next (함수) — request를 파라미터로 받아서 해당 경로 동작에 넘기고, 그 경로 동작이 만든 response를 돌려줘요.
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.perf_counter()
    response = await call_next(request)
    process_time = time.perf_counter() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

참고로 Request는 from starlette.requests import Request로 불러올 수도 있는데, FastAPI가 개발자 편의를 위해 그냥 노출해 주는 거예요. 원래 Starlette에서 온 것이죠.

응답 전후로 코드 실행하기

요청이 어떤 경로 동작에 닿기 전에, 그리고 응답이 생성된 후에 (반환되기 전에) 코드를 넣을 수 있어요. 위 예시는 요청을 처리·응답을 생성하는 데 걸린 시간을 초 단위로 담은 커스텀 헤더 X-Process-Time을 추가해요. 여기서는 time.time() 대신 time.perf_counter()를 쓰는 게 이런 측정에 더 정확해서 좋아요.

한 가지 팁이에요. 커스텀 헤더에는 X- 접두사를 쓰는 게 관례예요. 다만 브라우저에 있는 클라이언트가 그 커스텀 헤더를 보게 하려면, CORS 설정에서 expose_headers 파라미터로 그 헤더를 열어줘야 해요.

여러 미들웨어의 실행 순서

미들웨어를 여러 개 추가하면(@app.middleware() 데코레이터든 app.add_middleware() 메서드든) 각 새 미들웨어가 애플리케이션을 감싸면서 스택을 형성해요. 마지막에 추가된 미들웨어가 가장 바깥쪽이고, 첫 번째가 가장 안쪽이에요.

요청 경로에서는 바깥쪽 미들웨어가 먼저 실행되고, 응답 경로에서는 마지막에 실행돼요. 예를 들어:

app.add_middleware(MiddlewareA)
app.add_middleware(MiddlewareB)

이렇게 하면 실행 순서가 이렇게 돼요.

  • 요청: MiddlewareB → MiddlewareA → route
  • 응답: route → MiddlewareA → MiddlewareB

이런 스택 구조 덕분에 미들웨어가 예측 가능하고 통제 가능한 순서로 실행돼요.

다른 미들웨어

더 많은 미들웨어 얘기는 고급 사용자 가이드의 "고급 미들웨어(Advanced Middleware)"에서, 그리고 CORS를 미들웨어로 다루는 법은 다음 섹션(CORS)에서 볼 수 있어요.

더 알아보기