diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md index c920f06..fd5726c 100644 --- a/book/300_architecture/311_FastAPI_구조_원칙.md +++ b/book/300_architecture/311_FastAPI_구조_원칙.md @@ -95,8 +95,8 @@ utils ### LangGraph 워크플로우 - **복잡한 다단계 처리**: LangGraph 적극 활용 -- **체크포인트 필수**: PostgresSaver로 부분 재시도 가능하게 구현 -- **stateless 금지**: 체크포인트 없는 LangGraph는 일반 함수와 동일, 프레임워크 가치 없음 +- **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트를 두어 부분 재시도 가능하게 구현 (권장) +- **실험/경량 플로우**: stateless LangGraph도 허용하되, 추후 stateful 전환 여부를 문서나 주석으로 명시 ### router 계층 ```python @@ -161,13 +161,14 @@ async def get_connection(): ``` ### 금지 사항 -- ❌ router/services에서 직접 asyncpg.connect() +- ❌ 프로덕션 router/services에서 직접 asyncpg.connect() - ❌ 하드코딩된 DB URL - ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수) + - 마이그레이션/원샷 스크립트 등 서비스 외부 유틸에서는 직접 연결 허용하되, 프로덕션 요청 경로에서 재사용 금지 ## 7. 파일 크기 제한 -- **한 파일 최대 300줄** +- **한 파일 최대 300줄 권장** (핵심 모듈은 가급적 유지) - 초과 시 기능별 분리 - 예: `services/email_integration.py` (500줄) → `email_send.py` + `email_fetch.py` @@ -192,7 +193,7 @@ from app.services import coldmail_filter # ✅ 모듈 import - [ ] DB 접근은 state를 통하는가? - [ ] 비즈니스 로직이 router에 있지 않은가? - [ ] 순환 import 가능성은 없는가? -- [ ] 파일 크기가 300줄 이하인가? +- [ ] 핵심 파일은 300줄 이하로 유지할 수 있는가? ## 10. 예외 상황