Python 프로그래밍 고급: FastAPI 프로젝트 구조 구축 방법

 

FastAPI 기본 사항

이 글에서는 FastAPI 프로젝트를 구성하는 두 가지 주요 전략을 논의하고 각 전략이 더 적합한 시나리오를 알려드리겠습니다.

좋은 구조가 왜 중요한가요?

모범 사례에 따라 코드를 작성하는 가장 중요한 이유는 다음과 같습니다.

1. 향상된 확장성 : 잘 정리된 코드는 FastAPI 프로젝트가 성장함에 따라 원활하게 확장될 수 있습니다.
2. 유지 관리성이 향상됩니다 . 이해하기 쉬운 코드는 업데이트와 수정을 간편하게 해줍니다.
3. 간소화된 협업 : 명확한 구조는 팀이 효율적으로 협력하는 데 도움이 됩니다.

프로젝트 구조를 위한 핵심 원칙

FastAPI 애플리케이션을 구축할 때 다음과 같은 모범 사례를 따르는 것이 중요합니다.

1. 관심사 분리 : 라우팅, 모델, 비즈니스 로직 등 FastAPI 프로젝트의 다양한 측면을 분리하여 명확성과 유지 관리성을 개선합니다.
2. 모듈성 : FastAPI 애플리케이션을 재사용 가능한 모듈로 분할하여 코드 재사용과 구성을 촉진합니다.
3. 종속성 주입 : 종속성 주입은 구성 요소를 분리하기 위해 구현되며, 이를 통해 FastAPI의 코드가 더 유연하고 테스트 가능하게 되고 .  fastapi.Dependencies 와 같은 라이브러리를 사용할 수 있습니다.
4. 테스트 가능성 : 테스트 가능한 코드 작성을 우선시하고 종속성 주입 및 모킹과 같은 전략을 통해 FastAPI 애플리케이션의 테스트 및 품질 보증을 보장합니다.

구조화된 형식

FastAPI 애플리케이션은 다양한 프로젝트 요구 사항에 맞게 여러 가지 방식으로 구성할 수 있습니다.

프로젝트 구조에는 두 가지 주요 접근 방식이 있습니다. 하나는 파일 유형을 기반으로 하고, 다른 하나는 모듈 기능을 기반으로 합니다.

1. 파일 유형에 따른 구조화

이 접근 방식에서는 공식 FastAPI 튜토리얼 에 표시된 대로 파일이 유형(예: API, CRUD, 모델, 스키마, 라우터)별로 정리됩니다  .

이 구조는 범위가 작은 마이크로서비스나 프로젝트에 더 적합합니다.

.
├── app  
│   ├── __init__.py   
│   ├── main.py       
│   ├── dependencies.py 
│   ├── routers
│   │   ├── __init__.py
│   │   ├── items.py  
│   │   └── users.py  
│   ├── crud
│   │   ├── __init__.py
│   │   ├── item.py  
│   │   └── user.py  
│   ├── schemas
│   │   ├── __init__.py
│   │   ├── item.py  
│   │   └── user.py  
│   ├── models
│   │   ├── __init__.py
│   │   ├── item.py  
│   │   └── user.py  
│   ├── external_services
│   │   ├── __init__.py
│   │   ├── email.py          
│   │   └── notification.py   
│   └── utils
│       ├── __init__.py
│       ├── authentication.py  
│       └── validation.py      
├── tests
│   ├── __init__.py
│   ├── test_main.py
│   ├── test_items.py  
│   └── test_users.py  
├── requirements.txt
├── .gitignore
└── README.md

이 구조에서는

• app/: 주요 애플리케이션 파일이 들어있습니다.
• main.py: FastAPI 애플리케이션을 초기화합니다.
• dependencies.py: 라우터에서 사용되는 종속성을 정의합니다.
• routers/: 라우팅 모듈을 포함합니다.
• crud/: CRUD(생성, 읽기, 업데이트, 삭제) 작업 모듈을 포함합니다.
• schemas/: Pydantic 모드 모듈을 포함합니다.
• models/: 데이터베이스 모델 모듈을 포함합니다.
• external_services/: 외부 서비스와 상호작용하는 모듈을 포함합니다.
• utils/: 유틸리티 모듈이 포함되어 있습니다.
• tests/: 테스트 모듈이 포함되어 있습니다.

2. 모듈 기능 기반 구조화

두 번째 접근 방식에서는 패키지의 기능(예: 인증 하위 패키지, 사용자 하위 패키지, 게시물 하위 패키지)을 기준으로 파일을 구성합니다.

모듈식 기능 구조는 많은 도메인과 모듈을 포함하는 일체형 프로젝트에 더 적합합니다. 이렇게 하면 단일 하위 패키지에 필요한 모든 파일 유형을 그룹화하여 개발 효율성이 향상됩니다.

이 구조는 FastAPI Best Practices GitHub 저장소 에서 권장됩니다   .

이 구조에서는 각 패키지마다 고유한 라우터, 스키마, 모델 등이 있습니다.

fastapi-project
├── alembic/
├── src
│   ├── auth
│   │   ├── router.py         
│   │   ├── schemas.py        
│   │   ├── models.py         
│   │   ├── dependencies.py   
│   │   ├── config.py         
│   │   ├── constants.py      
│   │   ├── exceptions.py     
│   │   ├── service.py        
│   │   └── utils.py          
│   ├── aws
│   │   ├── client.py  
│   │   ├── schemas.py
│   │   ├── config.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   └── utils.py
│   └── posts
│   │   ├── router.py
│   │   ├── schemas.py
│   │   ├── models.py
│   │   ├── dependencies.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   ├── service.py
│   │   └── utils.py
│   ├── config.py      
│   ├── models.py      
│   ├── exceptions.py  
│   ├── pagination.py  
│   ├── database.py    
│   └── main.py
├── tests/
│   ├── auth
│   ├── aws
│   └── posts
├── templates/
│   └── index.html
├── requirements
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── .env
├── .gitignore
├── logging.ini
└── alembic.ini

이 구조에서는

모든 영역 디렉토리를  src 폴더에 저장합니다.

• src/: 공통 모델, 구성, 상수 등을 포함하는 애플리케이션의 최상위 수준입니다.
• src/main.py: 프로젝트의 루트 디렉토리에서 FastAPI 애플리케이션을 초기화합니다.

각 패키지에는 자체 라우터, 모드, 모델 등이 있습니다.

• router.py: 모든 엔드포인트를 포함하는 각 모듈의 핵심입니다.
• schemas.py: Pydantic 모델용.
• models.py: 데이터베이스 모델용.
• service.py: 모듈별 비즈니스 로직.
• dependencies.py: 라우터 종속성.
• constants.py: 모듈별 상수 및 오류 코드.
• config.py: 예를 들어 환경 변수.
• utils.py: 응답 정규화, 데이터 강화 등과 같은 비즈니스 로직이 아닌 기능
• exceptions.py: 모듈별 예외, 예  PostNotFound: InvalidUserData.

패키지가 다른 패키지에서 서비스, 종속성 또는 상수를 가져와야 하는 경우 모호성을 피하기 위해 명시적인 모듈 이름을 사용합니다.

from src.auth import constants as auth_constants
from src.notifications import service as notification_service
from src.posts.constants import ErrorCode as PostsErrorCode

마무리

요약하자면, FastAPI 프로젝트에 적합한 구조를 구축하는 것은 애플리케이션의 확장성, 가독성, 유지 관리를 위해 매우 중요합니다. 코드를 효과적으로 구성하면 코드를 쉽게 관리할 수 있고 변화하는 요구 사항에 적응할 수 있습니다.

우리는 FastAPI 프로젝트 구조의 두 가지 주요 유형, 즉 파일 유형 기반 구조와 모듈 기능 기반 구조에 대해 논의했습니다.

파일 유형 구조는 FastAPI에서 공식적으로 제시한 것으로, 파일을 파일 유형(예: 라우터, 패턴, 모델)별로 구성합니다. 이 구조는 각 서비스가 단일 책임을 갖는 마이크로서비스 아키텍처에서 잘 작동합니다.

반면, 모듈-기능 구조는 파일 유형이 아닌 모듈 기능을 기준으로 파일을 구분합니다. 이러한 접근 방식은 대규모 모놀리식 애플리케이션에 더 적합하며 구성 및 유지 관리가 더 용이합니다.

FastAPI 프로젝트의 구조를 선택할 때 프로젝트 규모, 복잡성, 아키텍처 설계와 같은 요소를 고려하세요.
파일 유형 구조나 모듈 기능 구조를 선택하든, 구성과 명확성을 우선시하는 것은 FastAPI 애플리케이션의 장기적인 성공에 도움이 됩니다.