# 유틸리티 함수 설계 원칙

**작성일**: 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`