🧠 FastAPI의 상태 관리와 의존성 주입 완벽 가이드

🕒 약 2분 읽는 데 소요됩니다

이전 글 보기(FastAPI에서 비동기 처리 완벽 이해)

– 전역 상태 관리부터 Depends 활용까지, 실전 사례 중심 설명

“코드가 커질수록 의존성은 관리가 아니라 통제의 대상이다.”
FastAPI는 소규모 실습부터 대형 서비스 아키텍처까지 확장 가능한 구조를 제공한다. 그 핵심이 바로 **상태 관리(State Management)**와 **의존성 주입(Dependency Injection, DI)**이다.

---

✅ 전역 상태 관리란?

FastAPI는 기본적으로 함수 기반으로 라우트를 정의한다. 이 구조는 가볍고 빠르지만, 때로는 애플리케이션 전역에서 사용할 수 있는 공통 자원, 예를 들어 DB 연결이나 설정 객체 같은 것을 저장해둘 필요가 있다.

1. 예: 전역 변수 사용

from fastapi import FastAPI

app = FastAPI()

counter = 0  # 전역 변수

@app.get("/increase")
def increase():
    global counter
    counter += 1
    return {"counter": counter}

• counter는 애플리케이션 실행 동안 유지된다.
• 하지만 이 방식은 멀티스레드/멀티프로세스 환경에서는 안정적이지 않다.

2. FastAPI 내부 상태 저장소 활용

FastAPI의 app.state 속성을 사용하면 전역 객체를 안전하게 저장할 수 있다.

@app.on_event("startup")
def startup_event():
    app.state.message = "Hello, FastAPI!"

@app.get("/message")
def read_message():
    return {"message": app.state.message}

• startup_event는 서버 실행 시 한 번만 호출됨
• app.state는 애플리케이션 전체에서 접근 가능함
• 이런 방식으로 DB 연결 객체도 저장할 수 있음

---

🧩 의존성 주입(Dependency Injection)의 개념

Dependency Injection이란, 필요한 자원(객체, 함수, 클래스 등)을 외부에서 주입받는 방식으로 코드 의존성을 줄이는 패턴이다.

FastAPI는 Depends()를 통해 이 기능을 아주 깔끔하게 구현한다.

---

🔧 Depends 기본 사용법

Depends는 파라미터처럼 보이지만, FastAPI가 자동으로 해당 함수를 호출해서 반환값을 주입해준다.

1. 예시: 공통 인증 로직 재사용

from fastapi import Depends, HTTPException

def verify_token(token: str = "my-token"):
    if token != "my-token":
        raise HTTPException(status_code=401, detail="Unauthorized")
    return token

@app.get("/secure-data")
def read_secure_data(token: str = Depends(verify_token)):
    return {"data": "This is secured"}

• verify_token() 함수가 먼저 실행되고, 그 결과가 token 파라미터로 주입됨
• 실패 시 예외를 발생시켜 라우트 접근을 차단함
• 이 구조는 인증/권한 검사, 로그 처리, DB 연결 주입 등에 활용 가능

---

🔁 다양한 DI 예제

2. 파라미터 있는 의존성

def get_settings(env: str = "dev"):
    return {"env": env}

@app.get("/settings")
def read_settings(settings: dict = Depends(get_settings)):
    return settings

• 의존성 함수도 파라미터를 가질 수 있고, FastAPI는 알아서 값을 바인딩해준다.

3. 클래스 기반 의존성

클래스를 이용하면 더 강력한 상태 관리가 가능하다.

class Config:
    def __init__(self):
        self.db_url = "sqlite:///./test.db"
        self.debug = True

def get_config():
    return Config()

@app.get("/config")
def read_config(config: Config = Depends(get_config)):
    return {"db_url": config.db_url, "debug": config.debug}

• 객체를 한 번 생성하고 재사용하거나, 필요 시 새로 만들어 줄 수도 있다.
• 보통 이 패턴은 설정, DB 커넥션, 서비스 객체 등에서 사용한다.

---

🔄 의존성의 중첩과 재귀 호출

의존성은 중첩 호출도 가능하다. 이건 규모가 커질수록 매우 유용한 패턴이다.

def get_db():
    db = "DB 커넥션 객체"  # 예시
    return db

def get_user(db = Depends(get_db)):
    return {"user_id": 123, "db": db}

@app.get("/me")
def read_me(user = Depends(get_user)):
    return user

• read_me()는 get_user()를 먼저 호출하고, 그 내부에서 get_db()를 호출한다.
• FastAPI가 의존성 그래프를 자동 분석해서 실행 순서를 정해준다.
• 이런 기능은 타 프레임워크에선 직접 구현하기 꽤 번거롭다.

---

💾 전역 DI로 전환하는 팁

대규모 프로젝트에서는 Depends를 전역 모듈처럼 정리해 사용하는 것이 좋다.

1. dependencies.py 파일 생성
2. 공통 의존성 함수를 정의
3. 각 라우트에서 import 후 Depends로 주입

# dependencies.py
def get_logger():
    return {"log": "Logging object"}

# main.py
from dependencies import get_logger

@app.get("/log")
def read_log(log = Depends(get_logger)):
    return log

이렇게 하면 코드 재사용성이 올라가고, 테스트도 훨씬 쉬워진다.

---

🧾 마무리 요약

FastAPI의 상태 관리와 의존성 주입은 규모 있는 API 서버 개발에 필수적인 요소다. 단순히 데이터를 주고받는 걸 넘어서, 공통 로직을 안전하고 깔끔하게 재사용할 수 있는 구조를 제공해준다.

기능	설명	실전 예
전역 상태 관리	앱 전체에서 공유하는 데이터 저장	DB 연결, 설정 객체 등
Depends()	함수/객체 주입을 자동 처리	인증, 로깅, 서비스 계층
중첩 DI	의존성을 또 다른 의존성존성을 또 다른 의존성으로 재귀적 구성	get_user(Depends(get_db))

---

이제 이 구조를 익히면, 실무에서 수십 개 라우트를 구성하면서도 일관된 방식으로 리소스를 주입하고 유지보수를 편하게 할 수 있다.

FastAPI 공식 문서 : https://fastapi.tiangolo.com/ko/