Skip to content

FastAPI 의존성 주입(Dependencies)

개요

여러 엔드포인트에서 인증 확인, DB 세션 얻기, 공통 파라미터 처리 같은 로직을 반복해서 쓰게 되면 코드가 금방 지저분해져요. FastAPI는 이 공통 로직을 의존성(dependency)으로 떼어 내고, path operation 함수가 "이걸 필요로 해"라고 선언하면 자동으로 주입해 주는 의존성 주입(DI) 시스템을 갖추고 있어요. 강력하면서도 사용법이 직관적이라, 다른 컴포넌트를 FastAPI에 통합할 때도 폭넓게 쓰입니다.

핵심 개념

의존성은 그냥 함수

FastAPI의 의존성은 평범한 함수예요. path operation 함수가 받을 수 있는 파라미터(쿼리, 본문, 헤더 등)를 똑같이 받을 수 있습니다. 예를 들어 공통 페이지네이션 파라미터를 묶어서 dict로 돌려주는 함수를 만들어 보죠.

async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}

이 함수는 path operation 함수처럼 선언만 하고, 필요할 때 Depends로 주입받으면 돼요.

Depends로 주입 선언

Depends는 Body, Query처럼 파라미터에 쓰이지만 동작은 조금 달라요. Depends에 넘길 수 있는 인자는 하나이고, 그건 함수 같은 것이어야 합니다. 사용할 때는 타입 힌트와 함께 적습니다.

from typing import Annotated
from fastapi import Depends, FastAPI

app = FastAPI()

async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons

Annotated는 FastAPI 0.95.0부터 지원(그리고 권장)되기 시작했어요. 그보다 낮은 버전에서는 Annotated를 쓰면 오류가 나니 버전 확인이 필요합니다.

중복 제거: Annotated 타입 공유

같은 의존성 선언을 여러 곳에서 쓰면 붙여넣기 코드가 늘어나죠. 그럴 땐 Annotated 타입을 한 번 정의해 재사용할 수 있어요.

CommonsDep = Annotated[dict, Depends(common_parameters)]

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

async 여부는 자유

의존성도 FastAPI가 직접 호출하므로 path operation 함수와 같은 규칙을 따라요. async def든 일반 def든 상관없고, 동기 안에 비동기 의존성이나 그 반대를 섞어 써도 FastAPI가 알아서 처리합니다.

통합·플러그인처럼 활용

의존성 주입 시스템으로 path operation 전에 실행되어야 하는 로직을 "이 함수는 이것에 의존한다"고 선언할 수 있어요. FastAPI는 이 시스템으로 사실상 무한한 통합·상호작용을 만들 수 있어서 별도의 플러그인 시스템이 필요 없다고 말할 정도예요. 그리고 모든 의존성이 추가하는 파라미터·검증도 OpenAPI 스키마에 자동으로 반영되어 인터랙티브 문서에 그대로 보입니다.

실제 적용 (데이터스케쳐스 관점)

FastAPI의 의존성 주입은 Python API에서 공통 로직을 분리하는 핵심 도구예요.

  • 벤더 중립 LLM 계층 — LLM 클라이언트나 세션을 의존성으로 만들어 여러 엔드포인트에서 재사용하고, 테스트에서 가짜 의존성으로 바꿔요.
  • 인증·설정 분리 — 토큰 검증, 설정 로드 같은 로직을 의존성으로 떼어 내 API 진입점을 깔끔하게 해요.
  • OpenAPI 문서화 자동 반영 — 의존성이 추가하는 파라미터·검증이 문서에 자동으로 나타나 계약이 명확해져요.

더 알아보기