From 875fa46f0dbf1beb12079a3a25acda8e0d6a9e5f Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Tue, 16 Dec 2025 14:51:13 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EC=9C=A0=ED=8B=B8=EB=A6=AC=ED=8B=B0=20?= =?UTF-8?q?=ED=95=A8=EC=88=98=20=EC=84=A4=EA=B3=84=20=EC=9B=90=EC=B9=99=20?= =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C=EB=9D=BC=EC=9D=B8=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- book/300_architecture/300_README.md | 1 + .../guidelines/utility_functions.md | 88 +++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 book/300_architecture/guidelines/utility_functions.md diff --git a/book/300_architecture/300_README.md b/book/300_architecture/300_README.md index ccf8155..1ac6125 100644 --- a/book/300_architecture/300_README.md +++ b/book/300_architecture/300_README.md @@ -25,6 +25,7 @@ Part 2에서 우리는 게임 메커니즘을 활용한 설계를 소개했습 - [네이밍 컨벤션](./guidelines/naming_conventions.md) - 파일명, 변수명, API 경로 규칙 - [로깅 규칙](./guidelines/logging_rules.md) - 로그 레벨, 포맷, 보관 원칙 - [상수/설정값 구조](./guidelines/constants.md) - 스킬 레벨, 타입, 감정 분류 구조 +- [유틸리티 함수 설계 원칙](./guidelines/utility_functions.md) - 코드 재사용성, 중복 제거 원칙 - [배포 패턴](./guidelines/deployment_patterns.md) - 배포 프로세스 패턴 **참고**: 자주 변하는 정보(포트, 엔드포인트, 환경변수 값)는 각 서비스 README.md 참조 diff --git a/book/300_architecture/guidelines/utility_functions.md b/book/300_architecture/guidelines/utility_functions.md new file mode 100644 index 0000000..ae84416 --- /dev/null +++ b/book/300_architecture/guidelines/utility_functions.md @@ -0,0 +1,88 @@ +# 유틸리티 함수 설계 원칙 + +**작성일**: 2025-12-16 +**목적**: 코드 재사용성 향상, 중복 제거, 유지보수성 개선 + +--- + +## 핵심 원칙 + +### 1. 중복 코드 제거 우선 +- 동일한 로직이 2개 이상의 위치에 반복되면 유틸리티 함수로 추출 +- 중복 코드는 버그 발생 가능성과 유지보수 비용 증가 +- 유틸리티 함수로 통일하여 한 곳만 수정하면 전체 반영 + +### 2. 범용성과 재사용성 +- 특정 도메인에 종속되지 않는 범용 함수로 설계 +- 다양한 상황에서 사용 가능하도록 매개변수화 +- 타입 안전성 지원 (타입 힌트, 타입 체크) + +### 3. 명확한 책임 분리 +- 하나의 함수는 하나의 명확한 작업만 수행 +- 함수명이 기능을 명확히 표현 +- 복잡한 로직은 여러 함수로 분리 + +--- + +## 유틸리티 함수 위치 + +### 디렉토리 구조 +``` +app/ +└── utils/ # 공통 유틸리티 함수 + ├── __init__.py + └── {domain}_extractor.py # 예: json_extractor.py +``` + +### 네이밍 규칙 +- 파일명: `{기능}_extractor.py`, `{기능}_helper.py` 등 +- 함수명: `extract_{대상}()`, `parse_{대상}()`, `format_{대상}()` 등 +- 명확하고 구체적인 이름 사용 + +--- + +## 설계 패턴 + +### 예시: JSON 추출 유틸리티 + +**문제**: LLM 응답에서 JSON을 추출하는 로직이 9개 위치에서 중복 + +**해결**: 범용 JSON 추출 함수 도입 +```python +# app/utils/json_extractor.py +def extract_json_from_text(text: str, expected_type: type = dict) -> Optional[Union[Dict, List]]: + """다양한 형식의 LLM 응답에서 JSON 추출""" + # 코드 블록, 설명 텍스트 등 다양한 형식 자동 처리 +``` + +**효과**: +- 9개 위치의 중복 코드 제거 (90줄 절약) +- 한 곳만 수정하여 전체 반영 가능 +- 다양한 LLM 응답 형식 자동 처리 + +--- + +## 재사용성 체크리스트 + +유틸리티 함수 생성 전 확인: +- [ ] 동일한 로직이 2개 이상의 위치에 있는가? +- [ ] 범용적으로 사용 가능한가? (도메인 종속성 없는가?) +- [ ] 함수명이 기능을 명확히 표현하는가? +- [ ] 타입 안전성을 지원하는가? +- [ ] 에러 처리가 적절한가? + +--- + +## 금지 사항 + +- ❌ 특정 도메인에 종속된 로직을 유틸리티로 만들지 않음 +- ❌ 너무 복잡한 로직 (책임 분리 필요) +- ❌ 한 곳에서만 사용되는 로직 (과도한 추상화 방지) +- ❌ 비즈니스 로직을 유틸리티에 포함 (서비스 레이어에 있어야 함) + +--- + +**참고**: +- JSON 추출 유틸리티 사례: `rb8001/app/utils/json_extractor.py` +- 관련 troubleshooting: `DOCS/journey/troubleshooting/251216_coldmail_processing_improvements.md` +