diff --git a/300_architecture/311_FastAPI_구조_원칙.md b/300_architecture/311_FastAPI_구조_원칙.md index b8fa2a1..f651372 100644 --- a/300_architecture/311_FastAPI_구조_원칙.md +++ b/300_architecture/311_FastAPI_구조_원칙.md @@ -1,7 +1,7 @@ # FastAPI 프로젝트 구조 원칙 **작성일**: 2025-09-17 -**수정일**: 2025-10-02 +**수정일**: 2025-10-02 (모범 사례 반영) ## 1. 계층 분리 원칙 @@ -30,9 +30,13 @@ ├── main.py # 앱 실행, 라우터 등록만 ├── app/ │ ├── router/ # HTTP 엔드포인트 +│ │ └── v1/ # API 버전 관리 (선택) │ ├── services/ # 비즈니스 로직 -│ ├── state/ # DB 접근 +│ ├── state/ # DB 접근 (Repository 패턴) +│ ├── models/ # ORM 모델 (DB 테이블 정의) +│ ├── schemas/ # Pydantic 모델 (API 요청/응답) │ ├── core/ # 설정, 공통 기능 +│ ├── db/ # DB 세션 관리 (선택) │ └── utils/ # 유틸리티 └── tests/ ``` @@ -40,7 +44,10 @@ ### 폴더 명명 규칙 - `router/` 또는 `api/`: HTTP 처리 - `services/`: 도메인 로직 -- `state/` 또는 `repositories/`: 데이터 접근 +- `state/` 또는 `repositories/`: Repository 패턴으로 CRUD 캡슐화 +- `models/`: SQLAlchemy 등 ORM 모델 +- `schemas/`: Pydantic 요청/응답 스키마 (models와 분리) +- `db/`: DB 엔진/세션 중앙 관리 (선택) - 복수형 사용 권장 ## 3. 파일 명명 규칙 @@ -53,19 +60,32 @@ - `{도메인}_{기능}.py`: coldmail_filter.py, ir_analyzer.py - 한 파일 최대 500줄 -### state/ +### state/ (Repository 패턴) - `database.py`: 통합 DB 접근 -- `{도메인}_repository.py`: 도메인별 분리 시 +- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화 (예: user_repository.py는 User 모델 CRUD만) + +### models/ +- `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py) + +### schemas/ +- `{도메인}_schema.py`: API 입출력 스키마 (예: user_schema.py, emotion_schema.py) ## 4. 의존성 방향 규칙 ### 단방향 흐름 ``` -router → services → state +router → services → state/repositories ↓ ↓ ↓ -utils core models +schemas core models + ↓ +utils ``` +### 계층 간 데이터 흐름 +- **router**: schemas로 요청/응답 검증 +- **services**: schemas + models 사용 가능 +- **state/repositories**: models만 사용 (DB 접근) + ### 금지 사항 - ❌ 순환 참조: A imports B, B imports A - ❌ 하위가 상위 호출: state가 services 호출 @@ -123,7 +143,14 @@ async def save_emotion(data: dict): ### 연결 방식 ```python -# state/database.py만 DB 연결 가능 +# db/database.py: DB 세션 중앙 관리 (권장) +from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession + +async def get_session() -> AsyncSession: + # 의존성 주입으로 세션 제공 + pass + +# state/database.py: 직접 연결 (간단한 경우) async def get_connection(): return await asyncpg.connect(os.getenv("DATABASE_URL")) ``` @@ -174,3 +201,13 @@ from app.services import coldmail_filter # ✅ 모듈 import # TODO: 계층 위반 - 리팩토링 필요 (issue #123) # 긴급 수정: 2025-10-02, 사유: DB 장애 복구 ``` + +## 11. 모범 사례 참고 + +본 문서는 FastAPI 커뮤니티의 다음 모범 사례를 반영하였습니다: + +1. **models/schemas 분리**: DB 스키마와 API 스펙 독립 관리 +2. **Repository 패턴**: state/repositories에서 CRUD 캡슐화 +3. **DB 세션 중앙화**: db/database.py에서 의존성 주입 +4. **API 버전 관리**: router/v1/, router/v2/ 구조 +5. **관심사 분리**: 요청/비즈니스/데이터 계층 명확한 역할 분담