FastAPI 디렉터리 구조, 2026년판 실전 가이드

FastAPI 디렉터리 구조, 2026년판 실전 가이드

"엔드포인트가 늘수록 PR이 미로가 된다"는 탄식이 들린다면, 폴더 구조를 손볼 시간이 왔다는 신호입니다.

1. 왜 2026년에 다시 구조를 얘기하나요?

FastAPI 0.110 이후(2025 Q4) 릴리스에서는 라우터 모듈화, lifespan 핸들러, Settings 관리가 표준 문서에 편입됐습니다. 동시에 DDD(도메인 주도 설계)를 차용한 대규모 서비스 사례가 늘면서, "app/main.py 하나"로 시작한 토이 프로젝트가 실서비스로 진화할 때 겪는 통증이 커졌습니다. 최신 공식 문서(“Bigger Applications”)와 커뮤니티 DDD 스캐폴딩을 조합해, 팀 규모에 맞춘 디렉터리 템플릿을 정리했습니다.

2. FastAPI 공식 문서가 제안하는 기본 레이어

app/
  main.py          # FastAPI 앱, lifespan, 미들웨어, 이벤트 후킹
  api/
    v1/
      endpoints.py # APIRouter 모음
      deps.py      # 공통 의존성
  core/
    config.py      # Pydantic Settings
    security.py
  models/
    user.py        # SQLModel / SQLAlchemy 모델
  db/
    session.py
  tests/
    test_users.py

• 핵심 포인트: APIRouter로 버전 디렉터리를 분리하고, Settings/DB 세션은 전역 모듈로 둡니다.
• 언제 적합한가: 팀 3~5명, 마이크로서비스로 쪼개기 전 단계. 모놀리식이라도 모듈 간 의존이 단순할 때 사용하면 됩니다.

3. DDD 스캐폴딩으로 확장하기

app/
  domain/
    user/
      models.py        # 엔티티, Value Object
      events.py
  application/
    user/
      commands.py      # UseCase/Service
      dto.py
  infrastructure/
    persistence/
      user_repo.py     # SQLAlchemy 구현
    gateways/
      email_ses.py
  presentation/
    api/
      v1/
        user_router.py
    schemas/
      user.py
  core/
    settings.py
    logging.py
  shared/
    kernel.py          # DI 컨테이너, MessageBus
  tests/
    unit/
    integration/

• 장점: 도메인 계층과 프레젠테이션 계층이 분리돼 테스트 범위를 명확히 지정할 수 있습니다.
• 주의: 디렉터리가 깊어지는 만큼 의존 규칙(예: presentation -> application -> domain 단방향)을 문서화하고 CI에서 점검해야 합니다.

4. 상황별 추천 구조

상황	추천 구조	비고
스타트업 MVP, 3인 이하	기본 공식 구조	단일 app 패키지, 라우터 분리만 적용
기능별 스쿼드 5~10명	하이브리드: domain/, application/ 도입	기존 api/, models/를 점진적으로 이동
멀티 서비스 + 이벤트 드리븐	풀 DDD + shared/ 메시지 버스	infrastructure에 Worker, 스케줄러 포함

5. 실무에서 확인한 운영 팁

• DI 컨테이너: Pydantic Settings + shared/kernel.py에서 punq, lagom, 혹은 단순 팩토리로 의존을 주입하면 테스트 격리가 쉬워집니다.
• 테스트 분리: tests/unit은 도메인/애플리케이션 계층만, tests/integration은 FastAPI TestClient와 실제 DB를 사용합니다.
• 코드 생성 도구: fastapi-codegen, cookiecutter-fastapi, 혹은 사내 스캐폴더를 통해 폴더 템플릿을 자동화하면 신규 도메인 추가가 빨라집니다.
• 관찰성: 구조가 깊어질수록 라우터 레벨 로깅, OpenTelemetry 계측, health check 경로(/healthz, /readiness)를 presentation 계층에서 일관되게 관리해야 합니다.

6. 도입 체크리스트

1. 도메인 바운더리 정의: user, billing, inventory처럼 도메인을 먼저 목록화합니다.
2. 의존 규칙 문서화: README나 ADR에 "presentation → application → domain" 단방향 규칙을 명시합니다.
3. CI 검증: pytest, ruff, mypy 외에도 deptry, import-linter로 계층 간 의존 위반을 자동 감시합니다.
4. 마이그레이션 전략: 레거시 app/models.py를 바로 삭제하지 말고, 새 DDD 구조로 옮기는 동안 어댑터 계층을 만들어 두세요.
5. 문서화: /docs/architecture.md에 디렉터리 목적, 생성 규칙, 샘플 코드 조각을 저장하면 신규 합류자가 빠르게 이해합니다.

FastAPI의 장점은 "빠른 프로토타이핑"이지만, 2026년에는 "예측 가능한 구조"가 동일하게 중요합니다. 공식 문서에 소개된 모듈화와 DDD 스캐폴딩을 상황에 맞게 혼합하고, 의존 규칙을 자동화된 검증으로 묶어두면 지속 가능한 API 팀 문화를 만들 수 있습니다.