From 3757467e46a56ad638ad3ef96452e231c1131406 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Sat, 29 Nov 2025 17:12:21 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20FastAPI=20=EA=B5=AC=EC=A1=B0=20?= =?UTF-8?q?=EC=9B=90=EC=B9=99=20=EB=AC=B8=EC=84=9C=20=EC=A0=95=EB=A6=AC=20?= =?UTF-8?q?(=EC=A4=91=EB=B3=B5/=EB=B6=88=ED=95=84=EC=9A=94=20=ED=91=9C?= =?UTF-8?q?=ED=98=84=20=EC=A0=9C=EA=B1=B0,=20=EB=AA=85=ED=99=95=EC=84=B1?= =?UTF-8?q?=20=EA=B0=9C=EC=84=A0)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../311_FastAPI_구조_원칙.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/book/300_architecture/311_FastAPI_구조_원칙.md b/book/300_architecture/311_FastAPI_구조_원칙.md index d5efb2c..086a094 100644 --- a/book/300_architecture/311_FastAPI_구조_원칙.md +++ b/book/300_architecture/311_FastAPI_구조_원칙.md @@ -19,7 +19,7 @@ | 계층 | 역할 | 금지 사항 | |------|------|----------| | **router/** | HTTP 요청/응답 처리만 | DB 직접 접근, 비즈니스 로직 | -| **services/llm/** | 비즈니스 로직 구현 | DB 직접 연결 (state를 통해서만) | +| **services/** | 비즈니스 로직 구현 | DB 직접 연결 (state를 통해서만) | | **state/** | DB CRUD만 | 비즈니스 로직 포함 | ## 2. 폴더 구조 규칙 @@ -43,7 +43,7 @@ ### 폴더 명명 규칙 - `router/` 또는 `api/`: HTTP 처리 -- `services/`: 도메인 로직 +- `services/`: 비즈니스 로직 - `state/` 또는 `repositories/`: Repository 패턴으로 CRUD 캡슐화 - `models/`: SQLAlchemy 등 ORM 모델 - `schemas/`: Pydantic 요청/응답 스키마 (models와 분리) @@ -62,7 +62,7 @@ ### state/ (Repository 패턴) - `database.py`: 통합 DB 접근 -- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화 (예: user_repository.py는 User 모델 CRUD만) +- `{도메인}_repository.py`: 도메인별 CRUD 캡슐화 ### models/ - `{도메인}_model.py`: ORM 모델 (예: user_model.py, emotion_model.py) @@ -95,8 +95,8 @@ utils ### LangGraph 워크플로우 - **복잡한 다단계 처리**: LangGraph 적극 활용 -- **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트를 두어 부분 재시도 가능하게 구현 (권장) -- **실험/경량 플로우**: stateless LangGraph도 허용하되, 추후 stateful 전환 여부를 문서나 주석으로 명시 +- **프로덕션 핵심 워크플로우**: PostgresSaver로 체크포인트 구현 (권장) +- **실험/경량 플로우**: stateless LangGraph 허용 ### router 계층 ```python @@ -152,7 +152,6 @@ async def save_emotion(data: dict): from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession async def get_session() -> AsyncSession: - # 의존성 주입으로 세션 제공 pass # state/database.py: 직접 연결 (간단한 경우) @@ -164,11 +163,11 @@ async def get_connection(): - ❌ 프로덕션 router/services에서 직접 asyncpg.connect() - ❌ 하드코딩된 DB URL - ❌ JSONB 저장 시 dict 직접 전달 (json.dumps() 필수) - - 마이그레이션/원샷 스크립트 등 서비스 외부 유틸에서는 직접 연결 허용하되, 프로덕션 요청 경로에서 재사용 금지 +- ❌ 프로덕션 요청 경로에서 직접 DB 연결 재사용 ## 7. 파일 크기 제한 -- **한 파일 최대 300줄 권장** (핵심 모듈은 가급적 유지) +- **한 파일 최대 300줄 권장** - 초과 시 기능별 분리 - 예: `services/email_integration.py` (500줄) → `email_send.py` + `email_fetch.py` @@ -204,8 +203,8 @@ from app.services import coldmail_filter # ✅ 모듈 import ### 예외 처리 시 ```python -# TODO: 계층 위반 - 리팩토링 필요 (issue #123) -# 긴급 수정: 2025-10-02, 사유: DB 장애 복구 +# TODO: 계층 위반 - 리팩토링 필요 +# 긴급 수정: 사유 명시 ``` ## 11. 로깅 원칙