[FastAPI] Middleware 미들웨어 (CORS, Logging)

1. 미들웨어란?

FastAPI의 미들웨어는 클라이언트의 요청(Request)와 응답(Response) 사이에 실행되는 가로채기 함수

• 주로 인증, 로깅, 성능 측정, 에러 처리, 보안 등 공통 기능을 구현하는데 사용 가능
• 비즈니스 & 도메인 로직을 분리할 수 있어, 가독성과 유지보수성 향상

 

 

2. FastAPI 예시

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
    
# https://fastapi.tiangolo.com/tutorial/middleware/?h=midd

 

http 요청이 들어왔을 때, 헤더에 "X-Process-Time" 이름으로 실행시간을 붙여주는 헤더를 붙여 주는 미들웨어

• request
  • 클라언트가 보낸 HTTP 요청 객체
  • 메서드, 경로, 헤더, 바디 등 요청에 대한 정보를 갖고 있음
• call_next
  • 다음 미들웨어 또는 라우터 함수로 요청을 전달하는 콜백함수
  • await call_next(request)를 호출하면, 이후의 요청 처리 과정(실제 라우터 함수)이 실행되고 Response 객체를 반환
  • call_next()를 호출하지 않으면 실제 라우트까지 요청 전달 X

curl 요청 : x-process-time 헤더가 추가된 응답

 

 

3. CORS

미들웨어를 통해 자주 해결하는 문제가 있는데,  CORS(Cross-Origin Resource Sharing) 교차-출처 리소스 공유 문제

1. 출처

출처(origin) = 프로토콜 (http/https) + 도메인 + 포트의 조합

 

아래는 모두 서로 다른 출처

• http://localhost
• https://localhost
• http://localhost:8080

 

2. CORS 동작 단계

1. 브라우저의 JS에서 다른 출처의 서버에 요청을 시도
2. HTTP OPTIONS (Preflight) 요청을 서버로 보냄 
   
   • 실제 요청을 보내기전에, 허용 여부를 확인하기 위한 사전 요청
   • Origin, Access-Control-Request-Method, Access-Control-Request-Headers 헤더가 포함됨
3. 서버가 CORS 허용 헤더를 응답으로 보냄 
   
   • Access-Control-Allow-Origin: http://localhost:8080
   • Access-Control-Allow-Headers: Content-Type, Authorization
   • Access-Control-Allow-Methods: GET, POST, OPTIONS
4. 브라우저가 응답을 판별 
   
   • 조건이 모두 맞으면 → 실제 요청을 보냄
   • 하나라도 안맞으면 → JS 레벨에서 차단

헤더 항목	판별 요구 사항	설명
Access-Control-Allow-Origin	요청한 Origin과 정확히 일치하거나 *	*와일드카드는 쿠키/인증정보와 함께 사용 불가
Access-Control-Allow-Methods	요청한 메서드(GET, POST 등)가 포함되어야 함	예: 실제 요청이 POST면, 응답에 POST가 포함되어야
Access-Control-Allow-Headers	요청한 커스텀 헤더들이 모두 포함되어야 함	예: Authorization, Content-Type 등
Access-Control-Allow-Credentials	(필요 시) true 설정	쿠키/세션 등을 주고받을 경우 필수
Status Code	응답 상태가 2xx여야 함	에러코드(4xx/5xx)면 무조건 차단됨

 

 

3. FastAPI CORS 설정

CORS에 대한 적절한 응답을 주기 위한 설정

from fastapi import FastAPI, Request
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# 허용할 출처(origin) 목록 정의
origins = [
    "http://example-fronted.com",  # 운영 중인 프론트엔드 도메인
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,            # 허용할 Origin 리스트 (필수)
    allow_credentials=True,           # 쿠키/세션 등 인증정보 허용
    allow_methods=["*"],              # 모든 HTTP 메서드 허용 (GET, POST 등)
    allow_headers=["*"],              # 모든 요청 헤더 허용 (Authorization 등)
)

# https://fastapi.tiangolo.com/ko/tutorial/cors/ - 일부 수정

 

 

OPTIONS  - 사전 요청 curl

curl -X OPTIONS http://localhost:8000/secure/data \
  -H "Origin: http://example-fronted.com" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: Authorization, Content-Type" \
  -i

 

CORS용 preflight - 정상적으로 응답

 

 

 

4. Logging

import logging
import time
from fastapi import FastAPI, Request, Response
from fastapi_cli import logging as fastapi_logging

app = FastAPI()
fastapi_logging.setup_logging(level=logging.INFO)
logger = logging.getLogger("fastapi_cli") # fastapi_cli set up

@app.middleware("http")
async def log_request_response(request: Request, call_next) -> Response:
    start = time.time()
    logger.error(f"[REQ] {request.method} {request.url.path}") # ERROR - log
    response = await call_next(request)
    duration = time.time() - start
    logger.info(f"[RES] {request.method} {request.url.path} → {response.status_code} | {duration:.2f}s") # INFO - log
    return response

 

 

ERROR -> INFO 출력 후, 응답

 

 

5. Auth

간단한 인증 절차는 구현할 수 있지만 → Depends (의존성 주입)을 통한 인증 설계를 하자

from fastapi import FastAPI, Request, HTTPException
app = FastAPI()

@app.middleware("http")
async def extract_user_from_header(request: Request, call_next):
    token = request.headers.get("Authorization")
    if token == "Bearer secrettoken":
        request.state.user = {"id": "user123", "role": "admin"}
    else:
        request.state.user = None
    return await call_next(request)

@app.get("/secure/data") # 보호된 라우터
async def secure_data(request: Request):
    if request.state.user is None:
        raise HTTPException(status_code=401, detail="Unauthorized")
    return {"message": f"Welcome {request.state.user['id']}"}

@app.get("/") # 공개 라우터
async def public():
    return {"message": "Anyone can access this route"}

 

 

 

 

요청			응답
경로	인증 헤더	명령어
보호된 경로	O	curl -H "Authorization: Bearer secrettoken" http://localhost:8000/secure/data	{"message":"Welcome user123"}
보호된 경로	X	curl http://localhost:8000/secure/data	{"detail":"Unauthorized"}
공개 경로	X	curl http://localhost:8000/	{"message":"Anyone can access this route"}

 

 

6. 관련 자료

https://fastapi.tiangolo.com/ko/tutorial/middleware/?h=%EB%AF%B8%EB%93%A4%EC%9B%A8%EC%96%B4

https://fastapi.tiangolo.com/ko/advanced/middlewares/?h=%EB%AF%B8%EB%93%A4%EC%9B%A8%EC%96%B4

https://fastapi.tiangolo.com/ko/tutorial/cors/?h=