[FastAPI] 대규모 프로젝트 설계 가이드: 모듈화, 의존성 주입, 라우터 분리

FastAPI 흐름도

FastAPI로 대규모 프로젝트를 설계할 때 모듈화, 의존성 주입, 라우터 분리가 핵심입니다. 아래 단계별 가이드와 예제 코드를 통해 체계적인 구조를 구축하는 방법을 설명합니다.

 

---

 

1. 프로젝트 구조 설계

 

권장 디렉토리 구조

my_project/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI 앱 인스턴스
│   ├── core/            # 코어 설정
│   │   ├── config.py    # 환경 변수 관리
│   │   └── security.py  # 인증/인가 로직
│   ├── api/             # API 엔드포인트
│   │   ├── v1/          # API 버전 관리
│   │   │   ├── users.py
│   │   │   └── items.py
│   ├── models/          # DB 모델 (SQLAlchemy)
│   ├── schemas/         # Pydantic 스키마
│   ├── services/        # 비즈니스 로직
│   ├── dependencies/    # 의존성 관리
│   └── db/              # 데이터베이스 연결
├── tests/               # 테스트 코드
└── requirements.txt     # 의존성 목록

 

---

 

2. 모듈화된 API 라우터 설계

 

라우터 분리 예시 (app/api/v1/users.py)

from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from ..schemas.user import UserCreate, UserResponse
from ..services.user_service import UserService
from ..dependencies import get_db

router = APIRouter(prefix="/users", tags=["users"])

@router.post("/", response_model=UserResponse)
def create_user(
    user: UserCreate, 
    db: Session = Depends(get_db),
    service: UserService = Depends(UserService)
):
    return service.create_user(db, user)

 

메인 앱에 라우터 등록 (app/main.py)

from fastapi import FastAPI
from app.api.v1 import users, items
from app.core.config import settings

app = FastAPI(title=settings.PROJECT_NAME)
app.include_router(users.router)
app.include_router(items.router, prefix="/items")

 

---

 

3. 의존성 주입(DI) 설정

 

데이터베이스 의존성 (app/dependencies.py)

from sqlalchemy.orm import Session
from app.db.session import SessionLocal

def get_db() -> Session:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

 

서비스 레이어 의존성 (app/services/user_service.py)

from sqlalchemy.orm import Session
from app.models.user import User
from app.schemas.user import UserCreate

class UserService:
    def __init__(self, db: Session):
        self.db = db

    def create_user(self, user_data: UserCreate) -> User:
        db_user = User(**user_data.dict())
        self.db.add(db_user)
        self.db.commit()
        self.db.refresh(db_user)
        return db_user

 

---

 

4. 데이터베이스 설정

 

SQLAlchemy 설정 (app/db/session.py)

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker
from app.core.config import settings

engine = create_engine(settings.DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

 

모델 정의 (app/models/user.py)

from sqlalchemy import Column, Integer, String
from app.db.base_class import Base

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True, index=True)
    email = Column(String, unique=True, index=True)
    hashed_password = Column(String)

 

---

 

5. 환경 변수 관리

 

설정 클래스 (app/core/config.py)

from pydantic import BaseSettings

class Settings(BaseSettings):
    PROJECT_NAME: str = "My FastAPI Project"
    DATABASE_URL: str = "sqlite:///./test.db"

    class Config:
        env_file = ".env"

settings = Settings()

 

---

 

6. 비동기 처리 고급 기법

 

async/await 활용 예시

from fastapi import APIRouter
from httpx import AsyncClient

router = APIRouter()

@router.get("/external-api")
async def call_external_api():
    async with AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()

 

---

 

7. 테스트 구조 설계

 

pytest 예시 (tests/test_users.py)

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_user():
    response = client.post("/users/", json={"email": "test@example.com", "password": "secret"})
    assert response.status_code == 200
    assert "email" in response.json()

 

---

 

8. 고급 패턴: Dependency Injector

 

복잡한 의존성 관리 (app/containers.py)

from dependency_injector import containers, providers
from app.db.session import SessionLocal
from app.services.user_service import UserService

class Container(containers.DeclarativeContainer):
    wiring_config = containers.WiringConfiguration(modules=[".api.v1.users"])

    db_session = providers.Factory(SessionLocal)
    user_service = providers.Factory(UserService, db=db_session)

 

---

 

결론: 대규모 프로젝트 관리 핵심 원칙

1. 모듈화: 기능별로 코드를 분리해 변경 시 영향 범위 최소화
2. 계층 분리: Route → Service → Repository 패턴으로 관심사 분리
3. 환경 관리: .env 파일과 Pydantic 설정으로 환경별 구성 관리
4. 비동기 최적화: I/O 작업 시 async/await 활용해 성능 향상
5. 테스트 자동화: pytest로 주요 시나리오 커버리지 확보

이 구조를 기반으로 프로젝트를 확장하면 팀 협업과 유지보수가 용이해지며, 안정적인 서비스 운영이 가능합니다.

 

[FastAPI] 대규모 프로젝트 설계하기

 

[FastAPI] RESTful API와 GraphQL API – 차이점, 구현, 선택 가이드