ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

docs: FastAPI 구조 원칙 문서 정리 (중복/불필요 표현 제거, 명확성 개선)

Browse Source
This commit is contained in:
Claude-51124 2025-11-29 17:12:21 +09:00
parent 6f257b0308
commit 3757467e46
1 changed files with 9 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
book/300_architecture/311_FastAPI_구조_원칙.md
View File

@ -19,7 +19,7 @@
| 계층 | 역할 | 금지 사항 | | 계층 | 역할 | 금지 사항 |
|------|------|----------| |------|------|----------|
| **router/** | HTTP 요청/응답 처리만 | DB 직접 접근, 비즈니스 로직 | | **router/** | HTTP 요청/응답 처리만 | DB 직접 접근, 비즈니스 로직 |
| **services/llm/** | 비즈니스 로직 구현 | DB 직접 연결 (state를 통해서만) | | **services/** | 비즈니스 로직 구현 | DB 직접 연결 (state를 통해서만) |
| **state/** | DB CRUD만 | 비즈니스 로직 포함 | | **state/** | DB CRUD만 | 비즈니스 로직 포함 |
## 2. 폴더 구조 규칙 ## 2. 폴더 구조 규칙
@ -43,7 +43,7 @@
### 폴더 명명 규칙 ### 폴더 명명 규칙
- `router/` 또는 `api/`: HTTP 처리 - `router/` 또는 `api/`: HTTP 처리
- `services/`: 도메인 로직 - `services/`: 비즈니스 로직
- `state/` 또는 `repositories/`: Repository 패턴으로 CRUD 캡슐화 - `state/` 또는 `repositories/`: Repository 패턴으로 CRUD 캡슐화
- `models/`: SQLAlchemy 등 ORM 모델 - `models/`: SQLAlchemy 등 ORM 모델
- `schemas/`: Pydantic 요청/응답 스키마 (models와 분리) - `schemas/`: Pydantic 요청/응답 스키마 (models와 분리)
@ -62,7 +62,7 @@
### state/ (Repository 패턴) ### state/ (Repository 패턴)
- `database.py`: 통합 DB 접근 - `database.py`: 통합 DB 접근
- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화 (예: user_repository.py는 User 모델 CRUD만) - `{도메인}_repository.py`: 도메인별 CRUD 캡슐화
### models/ ### models/
- `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py) - `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py)
@ -95,8 +95,8 @@ utils
### LangGraph 워크플로우 ### LangGraph 워크플로우
- **복잡한 다단계 처리**: LangGraph 적극 활용 - **복잡한 다단계 처리**: LangGraph 적극 활용
- **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트를 두어 부분 재시도 가능하게 구현 (권장) - **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트 구현 (권장)
- **실험/경량 플로우**: stateless LangGraph도 허용하되, 추후 stateful 전환 여부를 문서나 주석으로 명시 - **실험/경량 플로우**: stateless LangGraph 허용
### router 계층 ### router 계층
```python ```python
@ -152,7 +152,6 @@ async def save_emotion(data: dict):
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
async def get_session() -> AsyncSession: async def get_session() -> AsyncSession:
# 의존성 주입으로 세션 제공
pass pass
# state/database.py: 직접 연결 (간단한 경우) # state/database.py: 직접 연결 (간단한 경우)
@ -164,11 +163,11 @@ async def get_connection():
- ❌ 프로덕션 router/services에서 직접 asyncpg.connect() - ❌ 프로덕션 router/services에서 직접 asyncpg.connect()
- ❌ 하드코딩된 DB URL - ❌ 하드코딩된 DB URL
- ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수) - ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수)
- 마이그레이션/원샷 스크립트 등 서비스 외부 유틸에서는 직접 연결 허용하되, 프로덕션 요청 경로에서 재사용 금지 - ❌ 프로덕션 요청 경로에서 직접 DB 연결 재사용
## 7. 파일 크기 제한 ## 7. 파일 크기 제한
- **한 파일 최대 300줄 권장** (핵심 모듈은 가급적 유지) - **한 파일 최대 300줄 권장**
- 초과 시 기능별 분리 - 초과 시 기능별 분리
- 예: `services/email_integration.py` (500줄) → `email_send.py` + `email_fetch.py` - 예: `services/email_integration.py` (500줄) → `email_send.py` + `email_fetch.py`
@ -204,8 +203,8 @@ from app.services import coldmail_filter # ✅ 모듈 import
### 예외 처리 시 ### 예외 처리 시
```python ```python
# TODO: 계층 위반 - 리팩토링 필요 (issue #123) # TODO: 계층 위반 - 리팩토링 필요
# 긴급 수정: 2025-10-02, 사유: DB 장애 복구 # 긴급 수정: 사유 명시
``` ```
## 11. 로깅 원칙 ## 11. 로깅 원칙